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INTRODUCTION 

This document explains how to use the 5.3 release of the Operating System. 
It includes all relevant material from prior releases and also describes 
the new features of this release. The User's Guide does not explain each 
feature of the OS in detail; instead, it explains operations such as 
installing and booting the system, and presents the details of the Command 
Shell and Filer commands (see the Operating System Reference Manual for a 
complete description of the Operating system). 

Because the Operating System Reference Manual is not updated for each new 
release, the User's Guide also contains explanations of any new features or 
calls that may not fit into the above topics . The User's Guide assumes 
that the Operating System Reference Manual that you have is dated March 1, 
1982. 



CONFIGURATION 

The OS boots from either a Profile or a Twiggy. Most people will boot the 
OS from a Profile, and use another hard disk for the Monitor. 

The OS restricts how you can use the various devices. The OS treats the 
Corvus as a source of Monitor files, not as an OS volume. The Lisa screen 
can be accessed by either the OS or the applications. The Lisa screen can 
display either the "main screen" that is usually reserved for applications, 
or the "alternate screen" that is used for Lisabug, and. read and writelns 
for debugging. There is a MOVESOROC program to change where application 
readln and writelns are to be displayed. They may be displayed on either 
the main screen, the alternate screen, or an external Soroc. If you use an 
external Soroc, you can see both the main applications screen, and the 
debugging screen at the same time. If you wish to use a Soroc, attach it 
to channel A of the Lisa. 

When the OS boots from a Profile, that Profile must be attached to the 
parallel port (the connector farthest to the right when viewed from the 
front). This port is 'PARAPORT' to the OS and '&3' to the Monitor. 

Your other hard disks are attached to the N-Port card, which must (for now) 
be in Slot 2 (the middle slot). Starting from the bottom of the N-Port 
card, the ports are named '&4', '&5', and '&6' by the monitor, and 
'SL0T2CHAN1', ' SL0T2CHAN2 ' , and 'SL0T2CHAN3' by the OS. The monitor gives 
preference to disks attached to the bottom of the N-Port card, so your 
monitor disk should probably be attached to &4. 



Roth 1 October 1, 1982 



Confidential Guide to OS 



After you have installed the OS, run the OSCONFIG program. OSCONFIG 
produces a configuration file that defines, at boot time, which devices are 
attached at each port (&3 thru &6), and which ONE disk is the Monitor's 
working device, the device the OS can access Monitor files from. OSCONFIG 
also allows you to emulate a smaller machine. 

The devices OSCONFIG recognizes are Profile, Corvus, and printers. If a 
device isn't named in the configuration program, the OS doesn't see it even 
if you explicitly mount it. To change your configuration, rerun OSCONFIG 
and name the output file SYSTEM. CONFIG, on the boot device. Then physically 
switch to the new arrangement, and reboot the OS. If your boot volume 
contains no SYSTEM. CONFIG file, the only optional device configured is the 
disk on PARAPORT (&3) if there is one connected there. 



OS VOLUME TYPES 

The OS currently supports two types of file system volumes, one built on 
top of the Monitor's concept of logical volumes and one entirely 
independent of Monitor volumes. The type of OS file system volume built 
within a Monitor logical volume is what you've used for the last few months 
when running the OS under the Monitor on a single disk. 

Under the current OS, you can only access this type of volume on the 

designated Monitor working device. This type of OS volume CANNOT be a boot 

volume. It can reside anywhere on the disk and its access is totally 
protected by the Monitor's mount table. 

'OS Devices' is the term used to describe the second type of volume. This 
type of volume CAN be a boot volume. However, an OS device has only a 
single OS volume that must start at the beginning of the device. When you 
initialize that volume, you specify how many blocks (pages) are it has. 

The OS initializes the specified number of pages on the OS device. For 
example, if you specify 9720 blocks when initializing a Profile as an OS 
device, all 9720 blocks are rewritten from the front of the disk without 
regard for any Monitor volumes that already exist there. The OS doesn't 
check the mount table to avoid destruction of existing Monitor volumes. 

However, it is possible for a device to be both an OS and a Monitor device 
if you create the Monitor volumes BEYOND the portion of the disk used as 
the OS volume. To reserve room for the OS volume, create a Monitor volume 
(under the volume manager) starting at the first physical block (block 8) 
of the disk that has the same size as the number of blocks you need for the 
OS device. The remaining space is usable for other Monitor volumes. 
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WARNING: When initializing an OS device that is split between an OS volume 
and Monitor volumes, be sure to initialize the correct number of pages. 
Specifying too large a number of blocks results in the destruction of 
Monitor volumes that follow the OS volume. In general, BE CAREFUL when 
mixing OS volumes and Monitor volumes on one device. 

SYSTEM FILES 

The OS is distributed on Twiggys that hold a bootable copy of the OS, 
miscellaneous release files, and the installation utilities. The files 
below define the release. All files listed should be on the OS boot 
volume. All are required to boot and run the OS except for RS232TEST, 
OSCONFIG, and OSINSTALL. 



SYSTEM. OS - The main portion of the OS code. 

SYSTEM. SHELL - OS command shell 

SYSTEM. BT_PROF - The profile version of the OS loader 

SYSTEM. BTJTWIG - The Twiggy version of the OS loader 

SYSTEM. DEBUG - First part of Lisabug 

SYSTEM.DEBUG2 - Second part of Lisabug 

SYSTEM. LLD - Low level drivers 

SYSTEM. CONFIG - User-produced definition of desired configuration 

IOSPASLIB.OBJ - System runtime library 

INTRINSIC. LIB - Intrinsic unit directory 

RS232TEST - RS232 test program (optional) 

OSINSTALL. TEXT - Exec file that transfers files onto your OS working 
device 

OSCONFIG - Utility to generate a SYSTEM.CONFIG file 

MOVESOROC - Utility to move application WRITELN's between main 

screen, alternate screen, and external Soroc 
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The files in the following list may be useful to you, but are not required 
to install the OS. These files are used to prepare an application to run 
on the OS. 

SYSCALL.OBJ - Public system calls unit 

INSTALLING THE OS 

The following are the steps required to install OS 5.3 onto a Profile: 

1) Insert the bootable OS Twiggy in the top slot of your 

system, attach your target OS boot Profile to &3, the parallel port. 

2) Be sure the Sysmgr 'Zero' has been run at some time on your 
target OS boot Profile. OS devices need to have a valid volume 
table, both to avoid confusion when examining the drive from the 
Monitor, and to allow the OS to use the drive as the Monitor's 
working device if necessary. 

3) If you are developing programs on the Monitor to run on the OS, you 
must transfer the following files from the twiggy to a 

Monitor volume: 

IOSPASLIB.OBJ 
INTRINSIC. LIB 
SYSCALL.OBJ 

4) Boot the OS from the bootable twiggy (see the section below on booting 
the OS for directions). Press the right hand COMMAND and ENTER to 
display the alternate screen. 

5) Type 'P' to run the privileged filer and then type 'I' (for I(nit) 
to initialize your OS device (see the section on P(rivfiler if you 
need assistance). Use the name PARAPORT to identify your profile 
at position &3. Depending on whether you have any Monitor volumes 
on your profile, you may want to respond with less than the maximum 
device size (9720) when I(nit asks how many pages (blocks) it should 
initialize for the OS volume. The OS uses 1300 blocks of your boot 
volume. So you will want to create at least 1500 blocks even if you 
don't intend to store anything else on the volume. Note that the OS 
boot volume must have enough space for the 

swap space for the applications, and swap space for data segments. 
Therefore, the minimum recommended size is 2000 blocks. 
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6) Type 'Q' to return to the OS Shell. Then type 'F' to run the OS Filer. 
Once you are in the filer, type 'M' to mount your newly initialized 
profile using the name PARAPORT. The Mount command is described 
under the OS Filer. 

7) Type 'W to change your working directory to the name of your OS volume. 
If you don't change the working directory, the macro that transfers the 
system files to your OS boot volume will NOT run correctly. 

8) Type '0/ to return to the OS Shell. Once you are in the Shell, type 'X' 
to execute <-OSREL-OSINSTALL, a macro that transfers each of the following 
files into your initialized volume using the FTP utility 'T(rans': 

SYSTEM. OS 
SYSTEM. SHELL 
SYSTEM. BTJPROF 
SYSTEM. BTJTWIG 
SYSTEM. DEBUG 
SYSTEM. DEBUG2 
SYSTEM. LID 
IOSPASLIB.OBJ 
INTRINSIC. LIB 
RS232TEST 
OSCONFIG 
M0VES0R0C 
OSINSTALL.TEXT 

9) Quit the OS and wait for the system to reset itself. You should 
now be able to boot the OS from your Profile (see BOOTING below for 
instructions). 

10) Run OSCONFIG to configure any optional devices. 

Remember that the OS and UCSD file systems are not compatible. 
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HOW TO BOOT THE OS 

The boot prom can boot either the OS or the Monitor. To decide which 
system to boot and which device to boot from, the prom selects the FIRST of 
the following list of possibilities that it encounters: 

1. If one of the combinations of keys listed below is pressed at the 
right time, the prom selects the corresponding system/boot device. 

'Command' followed by '1' means boot the OS from the top 
Twiggy drive 

'Command' followed by '2' means boot the OS from the bottom 
Twiggy drive 

'Command' followed by '3' means boot the OS from the Profile 
on the parallel port 

The boot prom makes a soft click when it's ready for you to type a boot 
device keycode, and a second click when it's no longer receptive. 

2. If parameter memory is 'valid', the prom uses the boot device stored 
there. The parameter memory manager application writes parameter 
memory. 

3. Boot from the top twiggy. 



The Profile must be left on for each attempt to boot the OS. Hopefully, 
this won't endanger disk integrity. If you have a Corvus attached to the 
system, you may want to turn it off before powering the system off and on. 

After booting the OS, the alternate screen displays the OS version number, 
the devices in the current configuration, and the numbers of the available 
volumes. The alternate screen is not visible, because the main screen is 
displayed. After the boot is complete, you can display the alternate 
screen by pressing the right COMMAND key, then the ENTER key. 



SHUTTING DOWN THE OS 

Whenever a user process returns to the Shell, you can quit the OS. 
However, if a user-process exception or system exception occurs, special 
action is necessary to preserve the integrity of files. During the normal 
course of running the OS, user and system data destined for a disk volume 
may still be in memory. If you reset the machine and reboot while data is 
in the buffer, the disk will be in an inconsistent state. The table below 

describes several situations that cause this problem and recommends an 
action for each. 
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Error 



Action 



Exception in USER process 
such as divide by zero, 
bus error, address error, 
etc. 

NMI in USER process that 
is indicated by entering 
debugger in a domain other 
than zero AND without 
the debugger condition 
'D0MAIN=2, OVERIDDEN TO 0' 



Type 'g' from the debugger 
and the OS continues to 
abort the process and do any 
necessary clean up work. 

Type 'g' from the debugger 
to continue executing the 
process. To abort the 
process, induce an arti- 
ficial exception. One way 
to do this is to set PC to 
('pc 0') and then type 
'g'. The process will 
probably get an illegal 
instruction exception and 
the OS should be able to 
abort it and do any clean 
up work necessary. 
REMEMBER: this only works . 
if the domain IS NOT ZERO. 



Exception in system 
code 



NMI in system code 



Once in the debugger, type 
'OSQUIT' from the debugger 
and the OS attempts to shut 
down the OS file system in 
an orderly fashion. You 
might have to type 'OSQUIT' 
several times before it 
works. DO NOT use NMI and 
'rb' to reset the machine 
unless OSQUIT does not work 
after repeated attempts. 

Type 'g' to continue. To 
recover from a fatal error 
in the OS, type 'OSQUIT'. 
You may have to type 'OSQUIT' 
several times before it works 
DO NOT use NMI and 'rb' to- 
res et the machine unless 
OSQUIT does not work after a 
dozen or so attempts. 
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PROGRAM DEVELOPMENT 

To write a program that can run on the OS: 

1. Compile your program using the SYSCALL unit 

2. Link the compiled version of your program with IOSPASLIB 

3. X(ecute the program 

If you are writing the program on the monitor, you must boot the OS and 
T(ransfer the linked .OBJ file to an OS file volume before X(ecuting it. 
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THE OS COMMAND SHELL 

When the OS comes up, a system process (the Root process) looks on the OS 
volume for a program file named SYSTEM. SHELL. If the OS finds one, it uses 
it as the OS command shell. If the OS doesn't find a SYSTEM. SHELL file, 
the Root process complains and goes automatically to the file transfer 
utility. At this point you can transfer any file from the UCSD world to 
serve as the OS shell. When you leave the file transfer utility, the Root 
process again looks for SYSTEM. SHELL. It repeats this cycle until it 
finally finds and starts up a shell. 

To change the shell, kill the current SYSTEM. SHELL, transfer a new 
SYSTEM. SHELL to the OS volume, and then type '0/ to quit. The Q(uit 
command asks whether or not you want to restart the Shell. If you type 'n' 
or press the carriage return, the OS terminates the Shell and shuts down 
the system. If you type 'y' in response to the question, the OS recreates 
the Shell from SYSTEM. SHELL. This procedure assumes that your current 
shell can kill and transfer files. 

The position of a device determines its OS device name. The definitions of 
OS device names are as follows: 

-PARAPORT is the device attached to the parallel port. 

-SLOTxCHANy is the device attached to a 4-port card's slot x and 
channel y. Slots and channels are numbered 1, 2, and 3. Slot 1 
is the slot furthest from the power supply side of the machine; 
channel 1 is the bottom channel. EXAMPLES A drive connected to 
the bottom port on a 4-port card that is in slot 2 is mounted as 
device -SL0T2CHAN1. 



The remainder of this section presents the OS Command Shell line and 
explains the OS command shell options. The OS command shell behaves like 
the UCSD command shell; to invoke an action, type the first character of 
the option you desire. 

lisaOS: X(ecute, D(ebug, F(iler, P(rivFiler, T(ime, V(ers, 0(ff, Q(uit 



X(ecute Executes a program. It prompts for the name of 

the program file to execute and expects the full 
OS file system name of a file that is on the OS 
volume. You must compile a program that runs on 
the OS with the SYSCALL unit and link it with 
IOSPASLIB before transferring it to the OS file 
system. If the character '<' precedes the file 
name, the Shell assumes that the file is an exec 
file. OS exec file format is the same as the 
Monitor format. The system determines which type 
of volume an exec file resides on by the file name 
used (see the T(rans command). 
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D(ebug 



Debugs a program. D(ebug acts the same as the 
X(ecute command except that the program comes up 
with a breakpoint at its first instruction. Due 
to the breakpoint, the system enters Lisabug and 
you can debug as usual. After prompting for the 
name of the program to debug, the command asks if 
you also want to debug all the son processes. If 
you type 'n' for no, only the process created to 
run the. program comes up with the breakpoint at 
the first instruction. If you type 'y' for yes, 
every process created until the main program 
terminates comes up with a breakpoint on the first 
instruction. 



F(iler 

P(rivFiler 

T(ime 



L(ib 



Enters the Filer (described below). 

Enters the privileged Filer (described below). 

Displays the current date/time setting and lets you 
enter a new date and/or time if desired. Type <CR> 
to indicate no change. To change the date or time, 
enter the new date and/or time in the format that 
the prompt specifies. 

Re-installs the Intrinsic Unit Directory file in 
memory. The command assumes that the new 
INTRINSIC. LIB file is already on the OS volume 
and that the Shell is the only process running in 
the system. If any error occurs during directory 
installation, a system error results and you must 
restart the OS. You can transfer and use a new 
INTRINSICLIB and use it while the OS is rebooting. 
Usually, no problems should occur when installing 
a new directory. NOTE: you cannot change IOSPASLIB 
using this command; you must reboot the OS to change 
it. 



V(ers 



Lists module version numbers and the OS release 
number. The OS group uses it to determine which 
versions of the OS components are being used. 



0(ff 



Turns Lisa off. The user is warned that power is 
about to be turned off. Answering yes ('y' or 'Y') 
to the warning prompt terminates the Shell and turns 
off the Lisa. Any other answer returns to the Shell 
command line. 
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Q(uit Terminates the current Shell process. The user is 

asked if a new shell should be created or if the 
Operating System should be shut down and the Lisa 
reset (the power is left on). Note that the Q(uit 
and 0(ff commands are 

THE ACCEPTABLE WAYS TO LEAVE THE OS 
AND RETURN TO THE MONITOR. 

These alternatives allow the Operating System to 
completely close and flush files that are open 
and to put the disk in a consistent state. If you 
do not wish to shut down the the system, the OS 
tries to start another SYSTEM. SHELL program. Use 
this to change Shells while running under the OS. 
You can also type 'OSQUIT' to return to the Monitor. 
This alternative is not desirable but is encouraged 
if the other alternatives don't work. 



THE FILER 

There are two 'Filers' in the OS environment. The 'Filer' handles normal 
file operations. The 'PrivFiler' handles special privileged operations 
mostly used to manage volumes. 

When prompted for a device name, a response of <CR> is sufficient to 
specify the current working directory. In general, however, a response of 
<CR> to a prompt indicates that the command should be aborted. In those 
situations where <CR> means the current working directory, a response of 
<ESC> aborts the command. 

The first half of the Filer command line is: 

Filer: T(rans, L(ist, N(ew, K(ill, R(ename, M(ount, U(nmount , Q(uit, ? 

Note that '?' is a command, not a request for information. It causes the 
command prompt to flip to the other half of the command line and display 
the other available commands. The other half of the Filer command line is: 

W(orkingDir, S(afety, D(eleteFiles 

T(rans 

T(rans invokes the file transfer utility FTP. FTP transfers files from the 
Monitor to the OS and from OS files to other OS files. Give FTP the source 
file name using either the UCSD file name syntax or the OS file name 
syntax, depending on the file, and the destination file name using the OS 
syntax. The file types and the file name syntax is described below. If a 
file with the destination file name already exists, FTP asks you for 
confirmation before writing over the old file. Once the transfer is 
complete, FTP asks for the next file to transfer. Type <cr> to exit. 
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Because two different file naming conventions are in use here, perhaps an 
example will be useful: 

T(ransfer 

What Lisa or UCSD file to transfer? VOL :MYTEXT. TEXT <cr> 
What Lisa file to transfer into? -DISK-MYFILE <cr> 
What UCSD file to transfer? <cr> 



This example takes the Pascal text file MYTEXT.TEXT from the Pascal volume 
named VOL and places it in the Lisa file MYFILE that is on the Lisa volume 
named DISK. 

Note that Paslib now supports RESET/REWRITE to an OS file. Therefore the 
prompt for the name of the file to transfer accepts either an OS file name 
or a Monitor file name. 

Because Paslib supports both Monitor volumes and OS volumes, the following 
naming convention has been adopted in order to distinguish one type from 
the other. A file name represents a Monitor file only if a colon (:) is 
one of the characters in the name AND the leading character of the name is 
not a dash (-). So, for example, you can transfer an OS file named 
VOL: MYTEXT.TEXT as long as you add a dash to the beginning of the name. 
Note that even when you transfer a Monitor file that resides on the boot 
volume, you must type the volume number or name and the file name; typing 
only the file name is not sufficient to identify the file. 

T(rans currently can only transfer Monitor files that reside in one of the 
SHORT directory volumes on the Monitor working device. The command 
considers the large directory volumes on the Monitor device invalid and 
skips over them when searching the volume for the specified file. If you 
want to transfer a file that is currently in a large directory, create a 
short directory volume and transfer the necessary file or files to that 
directory while running under the Monitor. Then, boot the OS and transfer 
the files. The next release of the OS or Paslib will support large 
directory Monitor volumes. 

If you have multiple hard disks connected to your system via the 4-port 

card, you can only transfer the UCSD files stored on a single device. To 

select a working device you run the OSCONFIG program and copy the result 
into your OS boot volume. 

Note that the transfer utility does not recognize the new Monitor file name 
syntax (DEV/ VOL: FILE). 

If you transfer a file into the Lisa file INTRINSIC. LIB, the system asks 
you if it should install the new Intrinsic Unit Directory immediately. The 
system installs it if you respond 'Y' or 'y'. If you choose not to install 
the new directory at that time, you must use the L(ib command later to 
install it yourself before running any programs that use the new 
INTRINSIC. LIB file. 
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L(ist 

Lists the files on a given directory, their sizes and the disk space that 
each uses. The disk space size is the number of blocks (512 bytes) 
currently allocated to the file (the PEOF), whereas the file size is the 
number of bytes of data in the file (the LEOF). The file list also tells 
if a file is software theft protected. See the P(rotect command under the 
PrivFiler for more information on theft protection. 

N(ew 
Creates a new file. 

K(ill 
Deletes a file. 

R( ename 

Renames an existing file or volume. If a volume is renamed, you must 
precede the volume name with a dash. Do not specify the dash if you are 
renaming a file on the working directory* 

M(ount 
U(nmount 

The two commands permit you to manage multiple OS file system volumes. 

S(afety 

Toggles the safety switch of a file on or off. The command asks for a file 
name and then asks whether the switch should be turned on (respond 'y' to 
the question) or off (respond 'n' or just <CR>). If the safety switch of a 
file is on, the file can not be killed. 



W(orkingDir 

Displays the current working directory and then prompts for a new one. To 
change it, type the name of the new working directory; <CR> indicates no 
change. When changing the working directory, use a complete volume name 
(remember to include the '-') or the command has no effect. '-DEV9' and 
'-MyVol' are two example volume names. Once a working directory is set, 
partially specified pathnames are evaluated using that directory. If you 
UNMOUNT the volume containing the current working directory, the boot 
volume becomes the working directory. 
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D(eleteFiles 

Deletes files using a simple wild card mechanism. The command first asks 
for the name of the directory to be searched and then asks for the partial 
file name for the search. The partial file name is the initial characters 
of the file names you want. For example, if you type 'ABC', the Filer 
searches for any file beginning with 'ABC. If you type <cr>, all files in 
the directory match. After the directory search, D(eleteFiles prompts you 
to enter whether or not you want to delete the files, if any, that match 
the partial name. Type <ESC> to stop file deletion before going through 
the whole directory. 



THE PRIVILEGED FILER 

The P(rivFiler command line is: 

PrivFiler: 0(nline, E(ject, F(ix, Knit, Z(ap, N(ewTwig, W(riteBT, Q(uit, ? 

As with the Filer, the ? command flips to the other half of the PrivFiler's 
command line which is: 

D(ump 



0(nline 

Lists each currently mounted volume and the device it is mounted on. It 
also prints the name of the current working directory. 

E(ject 

Ejects a Twiggy disk from the specified device. Note that the button on a 
drive will not eject a disk; you must use the E(ject command. However, the 
command will not eject a disk that is still mounted. 

F(ix 

Invokes the Scavenger, the volume restoration utility program. It recovers 
lost space on a volume and repairs damaged file structures. You cannot run 
the Scavenger against the OS boot volume. If you attempt to scavenge the 
boot volume, the Scavenger returns error 1228. 

Knit 

Creates an OS file system volume. The volume initialized must not be 
mounted. After you specify the device name (without the '-'), the Filer 
asks for the set up information it needs. If the device is a diskette (not 
a Profile or the network), the media is automatically formatted. To 
initialize an entire disc, you may respond "0" to the number of blocks to 
initialize. 
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Although Knit destroys the current volume contents, the Pascal directory, 
if it is a small one, is untouched. Thus, the Monitor can still read the 
volume. Once you have initialized the volume, remember to mount it so you 
can use it. Boot tracks are automatically written to any initialized 
device as long as it is not the boot device. 

DO NOT attempt to Initialize an illegal device. 

Z(ap 

Invalidates an OS file system volume. To use the volume again, you have to 
initialize the volume the next time you start up the OS. If you change 
your mind after Zapping a volume, just Zap it again. Zap makes the volume 
appear to be an unmount able non-OS volume. The Z(ero command in the 
Monitor is not equivalent to Zap. 

N(ewTwig 

Formats a Twiggy diskette. The command prompts for the device name; 
"UPPER" or "LOWER" are appropriate names for Twiggies. After formatting 
the diskette, you should initialize it as an OS volume. Note that you no 
longer have to format a diskette before you initialize it. 

W(riteBT 

Writes boot track information on an initialized Twiggy diskette or Profile 
to allow you to boot the OS. NOTE: you can't write boot tracks on your 
boot volume. Instead, boot the OS from another Profile or Twiggy, attach 
your boot Profile to the N-port card, and then write boot tracks to it. 
Users following the standard OS installation procedures should not end up 
with a boot volume without boot tracks. Because boot tracks are 
automatically written when a volume is initialized, this function is useful 
mainly when new boot tracks need to be written and you do not want to lose 
the contents of the disk. 



D(ump 

Provides a nicely formatted hexadecimal and ASCII dump of any page in the 
Lisa file system. The OS group uses D(ump primarily as a debugging aid. 
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P(rotect 

Sets the software theft protection fields for the specified file. The user 
is asked for verification before the file is protected, because once it is 
protected, it cannot be unprotected. If the user verifies that it is to be 
protected by responding "y"» the file is made into a "virgin protected 
master." This means the file can only be copied by facilities that 
implement software theft protection, such as the Lisa Applications Filer. 
In particular, the S Shell will not be able to copy it with the T(ransfer 
command. The file can, however, be executed on any machine. The L(ist 
command of the filer indicates if a file is protected or not. Note that a 
protected file can be killed if desired. 

Q(uit 
Quit exits the PrivFiler and returns you to the OS command shell. 

THE ASYNCHRONOUS FILE SYSTEM 

Because your OS volume can only be on a Profile or a Twiggy, the OS blocks 
a process calling a system procedure that involves an I/O operation until 
the operation is complete. If there is a ready process at that time, the 
scheduler starts that process running during the time necessary for the I/O 
operation. 

This feature may improve overall performance of the OS. However, it can 
cause some problems. It is possible with this feature that writeln 
messages from several processes can get interspersed. This occurs if a 
writeln message from one process interrupts a writeln message from another 
process currently blocked for an I/O operation. 

Although this feature should not affect application programs, problems may 
occur with executing processes that share variables. A situation that 
could cause problems with shared data is the following. A process sets up 
a shared data address and then calls READ__DATA to this address. The 
READ_jDATA call blocks this process and allows a second process, possibly of 
lower priority, to run. If the second process attempts to use the shared 
data, it might receive erroneous data. If you have any problems protecting 
shared data, consult the OS group. 
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OS PERFORMANCE 

This section explains the file system improvements that are part of the 5.2 
release of the Operating System and suggests how you can take advantage of 
them to improve program performance. Optimizations occurred in the 
following areas: 

o Creation and killing of objects 

o Allocation and deallocation of space 

o Multiple-block I/O 

Reorganizing the catalogs speeded up creating and killing objects. The OS 
now uses a hashing technique to map an object name to a location within a 
catalog. Other internal reorganizations further reduce the I/O time 
required for most catalog accesses. In release 5.3, the degradation of 
GetJJext_Entry has been fixed. 

Space allocation and deallocation no longer write page label (hint) 
information. The write operation is postponed until data is written to the 
file because I/O has to occur at that time anyway. The implications of 
this change are: 

o Although allocation and deallocation are significantly faster, 
reliability may be somewhat reduced. It is very important to 
use the recommended shutdown techniques discussed earlier to 
guarantee that the file system information is flushed to disk 
in a consistent state. 

o Because automatic allocation on writes is still implemented, 
explicit allocation is useful mainly for guaranteeing the 
availability of disk space rather than for performance benefits. 



Major optimizations were made to take advantage of any opportunity to do 
multiple-block I/O. The larger the request, the better the increase in 
speed is likely to be. Conversely, you will probably see no significant 
improvement in I/O operations that deal with only one byte at a time. 
However, there should be some improvement of speed in such I/O operations 
due to the fact that automatic write through to the disk no longer occurs, 

To summarize, create and kill are much faster, allocate and deallocate, 
although much faster, are now useful mainly for managing availability of 
disk space, and reading and writing multiple blocks of data at a time is 
much faster. It is hard to state how much faster these operations are; 
feedback from user tests would be much appreciated. However, please see 
the Operating System group if you don't notice significant improvement in 
the above areas . 
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TWIGGY BAD BLOCK HANDLING 

Two new device control functions are available for Twiggy drives. One of 

them (decode * 20) returns status information on the Twiggy drive. The 
other (decode - 21) is used to control sparing. A program to call these 
functions appears as follows: 

VAR 

cparm: dctype; 

errnum: integer; 

path: pathname: 

BEGIN 

path := '-upper'; (* or path :* '-lower'; *) 

cparm. devers ion := 1; 

cparm. decode :■ 20; (* or cparm. decode := 21; *) 

cparm.dcdataf?] := ?; (* see below *) 

DEVICE__C0NTR0L( errnum, path, cparam); 
END; 



When decode ■ 20: 

dcdata[0] returns: 



- no disk present 

1 - disk present but not accessed yet 



returned values 2-4 only after first disk access (usually 
mount ) 

2 - bad block track appears to be 

unformatted 

3 - disk last formatted by some program 

other than the OS 

4 - OS formatted disk 



dcdata[l] returns: 



dcdata[2] returns: 



dcdata[3] returns: 



dcdata[4] returns: 



- no button press pending 

1 - disk present, button pressed, but not 

yet ejected 

number of blocks still available for 

remapping (0-16) 

(meaningful only when dcdatafO] ■ 4) 

- both copies of bad-block directory are 

intact 

1 - one of the bad-block directory copies 

is corrupt 
(meaningful only when dcdata[0] ■ 4) 

- automatic bad-block sparing is disabled 

1 - automatic bad-block sparing is enabled, 

and will occur as long as there are 
blocks available for remapping 
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When decode =21: 

dedata[0] set to: 



- disables automatic bad-block sparing 

1 - enables automatic bad-block sparing 

whenever there are blocks available 
for remapping (default) 



PRINTERS AND RS-232 INPUT/OUTPUT 

The Operating System supports the parallel ports and one serial RS-232 
port; the other RS-232 port is reserved for Lisabug on the standalone OS. 
The parallel ports on the 4-port card are named -slotxchany-any thing, where 
x and y are numbers 1 through three depending on the configuration. The 
device pathname for the OS supported RS-232 port is '-RS232B-any thing' 
where "anything' is any sequence of characters. RS232B is the leftmost 
port when facing the front of the machine. There is no device control 
required for printing on the parallel ports. The remainder of this section 
is devoted to serial printing. 

Follow the directions in this paragraph to set up a printer. Set the 
printer to handle 1200 baud serial communications. Connect the printer 
cable to a modem eliminator, and connect the modem eliminator to the RS232B 
port. If you want to connect the printer to a Soroc instead, set the Soroc 
to 1200 baud (set its rotary switch to 6) and connect the Soroc to the 
RS232B port using a standard Lisa-to-Soroc cable. 

The default configuration is no parity, DTR handshake, 1200 Baud. You can 
change the configuration by using the DEVTCE_C0NTR0L procedure. A sample 
program fragment that calls DEVICE_C0NTR0L follows. 

VAR 

cparm: dctype; 
errnum: integer; 
path: pathname; 

BEGIN 

path:='-RS232B'; 
cparm.dcversion: =s 2; 
cparm.dccode:* « w >> 

cparm. deda ta[0] :« « x » 
cparm.dcdata[l j := « y >> 
cparm.dcdata[2] :« « z ». 
DEVICE_C0NTR0L( errnum, path, cparm) ; 
END; 



(* note version change *) 
(* see below *) 



<< w », « x >>, << y », and << z » are defined as follows: 
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« y » « z » 



FUNCTION < 


< w » 


« x » 


Group A — Parity: 






No parity 


1 





Odd parity, no 


1 


1 


input parity 
checking 






Odd parity 


1 


2 


Even parity, no 


1 


3 


input parity 
checking 






Even parity 


1 


4 


Group B — Output Handshake 


' 




None 


11 


— 


DTR handshake 


2 


. — 


XON/XOFF handshake 


3 


— 


delay' after Cr, LF 


4 


ms delay 


Group C— Baud rate: 


5 


baud 


Group D— - -Input waiting: 






wait for full line 


6 





return whatever rec'd 


6 


1 


Group E — Input handshake: 






no handshake 


7 
9 



-1 



-1 65 



DTR handshake 7 

XON/XOFF handshake 8 

Group F — Input type-ahead buffer: 

flush only 9 

flush's re-size 9 

flush, re-size, 9 
and set thresh 
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bytes 
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hi 
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FUNCTION « w » « x » « y » « z » 

Group G — Disconnect Detection: 

none 10 — 

device on 

RS232B 10 -128 



To change the configuration, call DEVICE__C0NTR0L for the option you want in 
each group. You can set baud to any standard rate. However, 3600, 7200, 
and 19200 baud are available only on the RS232B port. 

'Low' and 'Hi' under Group F set the low and high threshhold in the type 
ahead input buffer. When 'hi' or more bytes are in the input buffer, XOFF 
is sent or DTR is dropped. Then when 'Low' or fewer bytes are in the type 
ahead buffer, XON is sent or DTR is re-asserted. The size of the type 
ahead buffer can be anywhere between and 64 bytes inclusive. 

Once the device is properly configured, OPEN a pathname 'RS232B-anything' 
where 'anything' can be any string of characters. You can now WRITEJDATA 
and READJDATA with any size data block to the refnum opened. 

STACK SIZE 

The stack size that a process requires depends on several factors. These 
include the amount of storage necessary for program global variables, 
regular unit global variables and intrinsic unit global variables, but do 
not include shared intrinsic variables. 

Besides the static stack space requirements, a process also requires stack 
space dynamically for procedure stack frames. These stack frames contain 
the procedure linkage information, procedure local variables, and space for 
temporary expressions. The initial amount of dynamic stack space is 
obtained from the program file the process is to execute and is allocated 
when the OS creates a process. The default initial dynamic stack size is 
10K (set by the Linker). The user can set the initial dynamic stack size 
to any desired value using the +S option of the Linker. 

During the course of execution, it is possible for a program to require 
more dynamic stack space than is currently allocated to the stack (stack 
overflow). When this occurs, the operating system automatically expands 
the stack by the necessary amount. Stack expansions occur as needed until 
an expansion would make the stack larger than the maximum stack size 
contained in the program file. The default value for maximum stack size is 
128K (again set by the Linker). You can set the maximum stack size to any 
desired value using the +T option of the Linker. 
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Under the current system, if a process requires a stack expansion that 
would cause the stack to exceed the maximum stack size, the process gets a 
bus error and enters LisaBug. Once in LisaBug, the system displays the bus 
error message and allows the user to do any debugging desired. To 
continue, type 'g' to exit LisaBug and allow the OS to abort the process. 

Under the final (production) system, the Operating System terminates a 
process needing more stack space than the maximum. The cause of the 
termination, located in the exception information block associated with the 
SYSJTERMINATE exception, will indicate 'stkjoverf low' (see Unit Syscall). 

Currently, the Operating System does not allow a stack size greater than 
128K (the size of a hardware segment). So if you specify a value greater 
than 128K in either the +S or +T option, the OS lowers it to 128K when the 
process is created. Note also that there can be a performance penalty 
associated with stack expansion since Memory Manager must be run in order 
to make space (possibly causing I/O) for the larger stack segment. 

INTRINSIC UNITS 

To use Intrinsic Units under the OS you need the Monitor release 8.0 
versions of the compiler and code generator, the 8.2 versions of the 
Intrinsic Unit Manager and Intrinsic Unit Linker, an INTRINSIC. LIB file, 
and the linked library file IOSPASLIB.OBJ found on the OS release disks. 

The INTRINSIC. LIB file used must contain the 4 units that comprise PasLib. 
These are units 1 (PASLIB), 102 (BLKIOINT), 103 (BLOCKIO), and 104 
(PASHEAP). The INTRINSIC. LIB file may contain anything else that you 
require for the application. Before using the INTRINSIC. LIB and 
IOSPASLIB.OBJ to link a new unit or program, you must Knstall the 
IOSPASLIB.OBJ from the OS release disk with the Intrinsic Unit Manager. 

The INTRINSIC. LIB file, IOSPASLIB.OBJ file, and any other library files 
required must be on the Monitor root volume and the OS volume before 
executing programs under the OS. 

You must compile programs that call OS routines using the SYSCALL unit. If 
a program calls anything from the privileged OS interface, you must include 
the PSYSCALL unit as well. In addition, you must link programs calling OS 
routines from either interface with IOSPASLIB.OBJ. 

Because both the INTRINSIC. LIB file and the various library files are 
required to run any programs that use Intrinsic Units, several problems can 
occur if you are not careful about keeping these files consistent with each 
other. If a library file is ever changed, you must re-install it in 
INTRINSIC. LIB, and, if you are using the monitor, you must transfer both 
the new library file and the new INTRINSIC. LIB to the OS volume. 

When you transfer a new INTRINSIC. LIB file to the OS volume, you must also 
change the memory resident copy of INTRINSIC. LIB. You can change the 
memory resident copy of the file either while in the T(ransfer command of 
the F(iler or later with the L(ib command of the Shell (see the 
descriptions of these commands for details). 
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If any of these steps are omitted, various errors can occur. For example, 
if you define a new Intrinsic Unit, build a program that uses the unit, but 
forget to transfer and change the INTRINSIC. LIB file on the OS volume, 
Make w Process returns an error saying that the unit was not found in the 
Intrinsic Unit Directory. The error occurs because it is not in the memory 
copy of INTRINSIC. LIB. 

As an aid in tracking these kinds of errors, the OS Loader currently 
displays the Intrinsic Unit number and name that was not found on the 
screen. This display will not be in the production system. Similar errors 
occur when you change the name or type of a unit and forget to transfer 
over the new INTRINSIC. LIB and/or library file before executing a program 
that uses the unit. 

More complicated errors can occur if the size of a shared code segment 
associated with an Intrinsic Unit or its location in a library file changes 
and the new INTRINSIC. LIB and/or library file is not transferred to the OS 
volume. In this case, the error is not detected until the code segment is 
swapped into memory. At this point, you get the message 

*** Error swapping in private code segment # nn for process id # pp 

OR 
*** Error swapping in shared code sement # nn (segname) for process 
id # pp 

where nn is the code segment number the application process uses, segname 
is the name of the shared segment from Intrinsic. Lib, and pp is the process 
identification number of the process for whom the segment is swapped in. 

If the swap-in error is for a shared segment, it is generally due to an 
inconsistency between Intrinsic. Lib and the library file containing the 
shared segment. If this is the case, the correct Intrinsic. Lib and the 
library file associated with the bad segment are probably not on the OS 
volume. 

If the swap-in error is for a private segment, it is generally due to 
either an improper link or a bad spot on the disk. To solve this problem, 
relink the program and transfer the relinked version to the OS volume. 

Regardless of the kind of swap-in error, type < ret > to continue. The OS 
terminates the failing process and the information block associated with 
the process's SYSJTERMINATE exception indicates that the OS is terminating 
the process due to a swap-in error. 
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ALTERNATE SCREEN 

The OS and PASLIB support an alternate screen, that is normally used to 
display writeln 's and the output from Lisabug. These types of outputs can 
go to one of three places: the main screen, the alternate screen, or an 
external Soroc. The main screen is usually used for the applications. 
Either the main screen or the alternate screen can be displayed on the Lisa 
screen. You can switch between the two by pressing the right hand COMMAND 
key and ENTER. 

The default for applications and OS's writeln's is the alternate screen. 
This means you must make the alternate screen visible in order to see the 
writeln. When you boot the OS, the main screen will be visible first until 
you press COMMAND and ENTER to make the alternate screen visible. You can 
type COMMAND and ENTER again to flip back to the main screen. 

The graphic output will always be shown on the main screen. Note that the 
keyboard input always goes to the currently visible screen (sometimes 
called the active screen), so a readln will not return until you make the 
alternate screen visible and type something to satisfy it. If there is a 
readln waiting and the alternate screen is not visible, the system will 
appear to be hung. If your Lisa application seems to be hung, try 
flipping to the alternate screen to see if there is a readln pending. 

There is a MOVESOROC program that you can execute to change where writeln 
and readlns appear. They may be sent to the main screen, the alternate 
screen, or to an external Soroc connected to RS232A. Note that you do not 
want to have writelns going to the main screen if you are running Lisa 
applications. With writelns going to the soroc, you can have simultaneous 
graphic and writeln output. Note that this program changes the 
applications writeln /readln only. The OS's writeln cannot be re-directed 
at run-time. In a later release, we will have a configuration program to 
change the console (writeln, readln) in parameter memory. This program 
will allow the OS's writeln to be redirected in the parameter memory also. 
This redirection will take effect at the next boot. 



PASLIB 

The OS does not support some of the Paslib routines. The remainder of this 
section explains how you use PASLIB routines in the OS world. If an 
unsupported function is called in the OS, the system displays the following 
message: 

MONITOR TRAP (E) occurred, index=<iiii> (routine name) in process of gid <gggg> 

where <iiii> is the routine's index to the Monitor's TRAP E handler. See 
the Pascal Development System Internal Documentation for the identity of an 
index without a routine name. 
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The OS does not support unit 10 routines such as Uni tread and Unitwrite and 
does not support the seek routine. However, it does support the G0T0XY 
routine, bp The Pas lib routines for value range check and string index 
check run in the OS environment. If the range check indicates an error in 
OS code, a system error is signalled. The message displayed is: 

VALUE RANGE ERROR in system code! 

value to check ** <vvw> lower bound « <nnnn> upper bound - <uuuu> 

return pc ■ <pppppp> caller a6 * <cccccc> 

Going to Lisabug, type g to continue. 



whe re : 



<pppppp> is the address of the next statement of the call 
to the range check routine in Paslib, 

<cccccc> is the address of the link field at the time of 
the call to paslib 



or: 



ILLEGAL STRING INDEX in system code! 

value to check =» <vwv> lower bound s <nnnn> upper bound ■ <uuuu> 

return pc = <pppppp> caller a6 * <cccccc> 
Going to Lisabug, type g to continue. 

In this case and for other errors in system code, use the OSQUIT facility 
described earlier instead of typing g to continue. If you type g and try 
to continue, you get system error 10201 and you must reboot the system. 

If a range check error occurs in application code, the system exception 
'SYS_VALUE__00B' is signalled. The message displayed is: 

VALUE RANGE ERROR in process gid <gggg> 

value to check ■ <ww> lower bound = <nnnn> upper bound • <uuuu> 

return pc ■ <pppppp> caller a6 * <cccccc> 

Going to Lisabug, type g to continue. 



or: 



ILLEGAL STRING INDEX in process of gid <gggg> 

value to check * <vvw> lower bound s <nnnn> upper bound » <uuuu> 

return pc =* <pppppp> caller a6 ■ <cccccc> 

Going to Lisabug, type g to continue. 
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If the process has not declared an exception handler for the exception that 
occurs, the system exception handler is entered after you type 'g' to 
contine. It terminates the process. If the process has declared a 
handler, the handler is called after you type 'g', and the process then 
continues execution. 

The intrinsic procedure HALT calls TERMINATE_PROCESS without passing an 
event • 

The block 10 routines, RESET, REWRITE, BLOCKREAD, BLOCKWRITE, and IORESULT, 
act in the operating system just as they do in the Monitor. In fact, RESET 
and REWRITE accept both Monitor and OS file names. 

In order to distinguish between the two types of files in RESET and 
REWRITE, Pas lib has adopted the following file naming convention: a file 
name designates a Monitor file only if the name includes a colon (:) AND 
does not begin with a dash (-). All other files are considered OS files. 



You can override the file system mode with a call to SetMPrefix. This call 
allows you to choose the file system you want; its format is: 

procedure SetMPrefix (var errnum: integer; 

prefix: vid); 



where vid is of type string [ 7 ] . . If you set prefix to '%%0S', later 
calls to RESET or REWRITE assume that file names refer to OS files. If you 
set prefix to '%%M0', subsequent calls to the two routines assume that file 
names refer to Monitor files. The file naming conventions given above are 
in effect if you set prefix to '%%B0'. The file system mode you choose 
remains in effect until the next call to SetMPrefix. 

Before calling SetMPrefix, you must declare it as external. This call will 
no longer be necessary once the entire development system is running on top 
of the OS and OS support of Monitor volumes isn't necessary. 

The OS file system mode does not support the file name construct [X], where 
X is a number of blocks. There is no need for the OS to support this 
syntax because an OS file expands as needed, and will not take the largest 
available space if X is not specified. In fact, if you do append the 
construct to the file name, it becomes part of the file name. 

IORESULT, in the OS file system mode, returns the same error values as 
Monitor files, but the error return numbers are in the OS file system 
range. The current mapping of OS to UCSD file system error values is: 
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OS Error Value 



UCSD Error Value 



882 
894 

921, 946 
941 
948 



8 
6 
7 
5 
10 



Other errors are not mapped. The above error mappings will no longer exist 
once the OS stops supporting Monitor files. 

Note also that IORESULT now returns error 11 (duplicate file) as a warning 
(-11) and completes the operation as normal when the error results from a 
second REWRITE of a file without a CLOSE after the first REWRITE. This 
change allows the user to decide whether to continue the program if the 
error occurs because of a program crash or to stop execution if there is a 
name conflict with another program that has already done a REWRITE to the 
same file. 

For Monitor files, only units 5, and 9 through 20 are considered block 
structured devices. Block 10 to a non-block structured device is not 
supported. IORESULT can return an additional error numbers 

17 - device error, non-zero value returned from last LISAIO call 

Text file block 10 works as expected. RESET and REWRITE of a text file 
(.TEXT suffix) sets the current block number to 2, thereby bypassing the 
text file header blocks. Note that RESET and REWRITE only accept names of 
files on the working device. In addition, the two routines do not support 
the new Monitor file name syntax (DEV/VOL: FILE) yet. 

In this release of PASLIB, the seek routine is finally supported. Also, 
there are three virtual devices supported in this PASLIB, '-CONSOLE', 
'-KEYBOARD', and '-PRINTER'. The -CONSOLE device works the same way as 
CONSOLE: in the monitor. The -KEYBOARD is a non-echoing input device 
intended to replace the uni tread of unit number 2 function. These two 
devices can be opened by a RESET: 

VAR keyboard: interactive 
RESET (keyboard, '-KEYBOARD'); 
READ (keyboard, ch); 
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Note that the -KEYBOARD device follows the characteristics of the -CONSOLE 
device and returns a space when a carriage return is entered. The -PRINTER 
device must be opened by a REWRITE and passed -PRINTER as the file name. 
Either write/writeln or blockwrite can be used to send data to the printer. 
Current implementations of writeln and blockwrite are transparent to the 
contents of data, i. e. blockwrite does not expand 'DLE' to spaces if the 
buffer contains blocks read in from a text file with blockread. 

In this release fo PASLIB, you can only connect the C.Itoh printer to the 
slot2chan2 port , and the switch 1-8 must be in the closed position. 
Eventually, there will be a configuration program to allow the C.Itoh 
printer to be on any parallel interface port, and the Qume printer to be on 
any parallel or serial port. 



THE PASCAL HEAP 

The heap is one contiguous piece of memory. It obtains a contiguous piece 
of memory with a call to MakeJDataseg. The heap works automatically 
without any initialization call; there are default values for size of the 
heap, the LDSN used, etc. 

Most users of the heap should use it the same way as they use the Monitor 
heap. For those having special needs, there is a call, PLINITHEAP, that 
specifies the LDSN, the initial heap SIZE, whether the heap can be swapped 
to disk, and the heap DELTA size. When you use PLINITHEAP, you must call 
it before making a call to the other heap routines. 

PLINITHEAP ( ERROR, REFNUM, SIZE, DELTA, 9, FALSE); 

PLINITHEAP is defined as follows in the PASLIBCALL unit: 

procedure PLINITHEAP (var ERNUM, REFNUM: integer; 

SIZE, DELTA: longint; 
LDSN: integer; 
SWAPABLE: boolean); 



where ERNUM is the error number returned if the procedure has any problems 
making a data segment having a mem_size of SIZE bytes, LDSN is the LDSN 
used for the heap ( the default is 5), REFNUM is the refnum of the heap, 
DELTA is the amount the data segment increases when the current space is 
used up (If you use a large heap, use a large number for DELTA), and 
SWAPABLE is the boolean that determines whether the system can swap the 
heap data segment out to disk if it needs to. 

When a Pascal program starts execution, there is no heap space allocated 
(no data segment made). On the first call to one of the heap routines or 
on the first PLINITHEAP call, the heap is created with either a default 
size of 16k bytes or the size specified in the PLINITHEAP call. 



? 
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PLINITHEAP makes the heap as a private data segment so that the OS will 
remove it when the process calling PLINITHEAP terminates. Note that when 
the heap is initialized, size and delta are put on 512 byte block 
boundries. Therefore, if you use the PLINITHEAP call and specify. values 
for size and delta that don't fall on block boundaries, the procedure 
increases the values to the next block boundary. 

If the heap runs out of space while it is being used, the size of the heap 
is increased by the default of 16k or the DELTA specified in PLINITHEAP. 
The default LDSN used is LDSN 5. If you want a different LDSN for the heap 
data segment, call PLINITHEAP. Remember that the size of a data segment is 
limited by the LDSN you use. For LDSN 16, you can only get 128k (actually 
96k safely), for LDSN 15 256k, for LDSN 14 384k, 



.... 



If SWAP ABLE is true, the heap is made with disc_size equal to SIZE so the 
data segment will not be memory resident. The default for SWAPABLE is 
false. When SWAPABLE is false the procedure creates a data segment that 
has a disc^size of which makes it memory resident. 

The unit PASLIBCALL contains the interface for the PLINITHEAP call. 
PASLIBCALL will contain the interface to all procedures that effect the 
PASLIB. PASLIBCALL will be released with Tippe. 

Currently, the OS supports the built in Pascal heap routines NEW, MEMAVAIL, 
MARK, and RELEASE. 

If you call NEW and there is not enough space, the size of the heap is 
increased by the default of 16k or the deltasize specified in PLINITHEAP. 

MEMAVAIL gives you the maximum number of words you could ever expect to get 
and takes into account the LDSN you used as well as the amount of free 
space the OS currently has available. If there is another process using 
memory concurrently, it's use of memory also effects MEMAVAIL. MEMAVAIL 
does not show the amount of memory left in the heap's data segment alone 
since the heap's data segment can grow and shrink over time. 

MARK works as it does in the Monitor. 

If you release the heap to a point within the original size of the heap 
data segment, the heap data segment is reduced to its original size. Other 
than this, RELEASE works as it does in the Monitor. 

The current heap could be replaced later by heap routines within the 
standard storage manager. There are currently implementation dependencies 
in the Compiler, and probably other parts of the system, that require a 
UCSD style contiguous heap. If these dependencies are removed in time, we 
may go to a fancier heap for first release that contains DISPOSE and 
possibly other features. 
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THE OS INTERFACE 

UNIT syscall; 
INTRINSIC; 

INTERFACE 



(* system call definitions unit *) 



CONST 

maxjename = 32; 
max_label__size = 128; 
len_exname = 16; 
size exdata ■ 11; 



size_etext ■ 9; 
size waitlist = 10; 



call__term = 0; 






ended = 1 ; 






self killed - 


2 




killed 


3; 




fthr_term = 


4 




bad_syscall ■ 


5, 




bad_errnum = 


6 




swap_error ■ 


7 




stkjoverf low ■ 


■ I 


3; 


da t a__overf low 


ss 


9; 


parity__err = 


1C 


); 


def_jdiv__zero 




■ n 


def_yalue__oob 




» 12 


def_ovfw 




» 13 


def_nmijkey 




■ 14 


def_range 




■ 15 


def str index 




' 16 



bus_error =21; 
addr_error ■ 22; 

illg_inst - 23; 
priv_violation = 24; 
line_1010 = 26; 
line 1111-27; 



diy__zero 

val„ue__oob 

ovfw 

nmi__key 

value__range 

str index 



31 
32 
33 
34 
35 
36 



(* maximum length of a file system object name *) 
(* maximum size of a file label, in bytes *) 
(* length of exception name *) 

(* 48 bytes, exception data block should have the same 
size as r__eventblk, received event block *) 

(* event text size - 40 bytes *) 

(* size of wait list - should be same as reqptr list *) 



(* exception kind definitions for 'SYSJTERMINATE' 
exception *) 

process called terminate__process *) 
process executed 'end' statement *) 
process called killjprocess on self *) 
process was killed by another process *) 
process's father is terminating *) 
process made invalid sys call - subcode bad *) 
process passed bad address for errnum parm *) 
process aborted due to code swap-in error *) 
process exceeded max size (+T nnn) of stack *) 
process tried to exceed max data space size *) 
process got a parity error while executing *) 



default handler for div zero exception was called *) 
for value oob exception *) 
for overflow exception *) 
for NMI key exception *) 

for 'SYS_yALUE_00B' excep due to value range err *) 
for ' SYS_VALUE_OOB ' excep due to string index err*) 

bus error occurred *) 

address error occurred *) 

illegal instruction trap occurred *) 

privilege violation trap occurred *) 

line 1010 emulator occurred *) 

line 1111 emulator occurred *) 

(* exception kind definitions for hardware exception *) 



(* excep kind for value range and string index error *) 
(■* Note that these two cause ' SYS_VALUE__00B ' excep *) 
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TYPE 

pathname = string [255]; 

e_name = string [max__ename]; 

names tring = string [20]; 

procinf oRec ■» record 

progpathname 
global_id 
fathered 
priority- 
state 
data_in 
end; 



pathname; 

longint ; 

longint ; 

1..255; 

(pactive, psuspended, pwaiting); 

boolean 



Tdstype ■ (ds_shared, dsjprivate); (* types of data segments *) 



dsinfoRec » 



record 

mem__size : longint; 

disc__size : longint ; 

numbjapen : integer; 

Idsn : integer; 

boundF : boolean; 

presentF : boolean; 

creatorF : boolean; 

rwaccess : boolean; 

segptr : longint; 

vo lname : e_name ; 
end; 



t_ex_name ■ string [ len_exname ] ; 

longadr * *longint; 

t_ex_state = (enabled, queued, ignored); 

pjexjdata « *t_exjdata; 

t_ex_data ■ array [0. .size_exdata] of longint; 

t__ex__sts ■ record 

ex__occurred_f : boolean; 

exjs tat e : t__ex_s ta t e ; 

numjexcep : integer; 

hdl_adr : longadr; 
end; 



(* exception name *) 

(* exception state *) 

(* exception data blk *) 

(* exception status *) 

(* exception occurred flag*) 

(* exception state *) 

(* number of exceptions q'ed*) 

(* handler address *) 
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p_env__blk » *env_blk; 


envjslk * recorc 


I 


pc : 


longint 


sr : 


integer 


dO : 


longint 


dl j 


longint 


d2 , 


longint 


d3 : 


longint 


d4 ! 


longint 


d5 


. longint 


d6 


: longint 


d7 


: longint 


aO 


: longint 


al 


longint 


a2 


: longint 


a3 


: longint 


a4 


: longint 


a5 


: longint 


a6 


: longint 


a7 


: longint 


end; 





(* environment block to pass to handler *) 
(* program counter *) 
(* status register *) 
(* data registers - 7 *) 



(* address registers - 7 *) 



p_term_ex_data ■ ~termjex_data; 

term_ex__data « record 

case excep_kind : longint of 
call_term, 
ended , 

self__killed, 
killed, 
f thr_term, 

bad_syscali, 
badjerrnum, 

swap__error, 

stk_overflow, 

da t ajove rf low , 

parity__err : (); 



(* terminate exception data block *) 



illg_inst, 
priv_violation, 

line_1010, 
lineal 111, 
defjdivjzero, 
def _value__o ob , 
def_ovfw, 
def_nmi_key 

: (sr : integer; 
pc : longint ) ; 
def _range , 



(* due to process termination *) 



(* due to illegal instruction, 

privilege violation *) 

(* due to line 1010, 1111 emulator *) 



(* terminate due to default handler for 
hardware exception *) 

(* at the time of occurrence *) 
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def str index 



: (value_check 
upperjbound 
lowerjDound 
returnj>c 
caller_a6 
bus__error, 
addr_error 

: (fun field : 



(* 



integer; 
integer; 
integer; 
longint ; 
longint ) ; 



terminate due to default handler for 
'SYS_VALUEjOOB' excep for value 
range or string index error *) 



(* due to bus error or address error *) 



packed record 

filler : 0..$7ff; 
rj» flag : boolean; 



end; 



i_n_flag : 
funjcode : 
end; 

access__adr : longint ; 
instjregister : integer; 
sr_error : integer; 
pc_error : longint); 



boolean; 
0..7; 



(* one integer *) 
(* 11 bits *) 



(* 3 bits *) 



pjhard^ exjdata ■■ ~hard_exjiata; 

hard_ex_data * record (* hardware exception data block *) 

case excep_kind : longint of 
divjeero, value__oob, ovfw 
: (sr : integer; 
pc : longint); 
value_range , s trJL ndex 
j (value check : integer; 



upper__bound 
lowerjaound 
return__pc 
caller a6 



integer; 
integer; 
longint; 
longint ) ; 



end; 



accesses = (dread, dwrite, append, private, global_ref num) ; 

mset ■ set of accesses; 

iomode ■ (absolute, relative, sequential); 

UID ■ record (*unique id*) 

a,b: longint 
end; 



times tmp_interval - record 

sec : longint; 
msec : 0..999; 
end; 



(* time interval *) 
(* number of seconds *) 
(* number of milliseconds within a second *) 
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info__type ■ (device_t, volume__t, object_t); 

devtype ** (diskdev, pascalbd, seqdev, bitbkt, non_io); 

filetype • (undefined, MDDFfile, rootcat, freelist, badblocks, 
sysdata, spool, exec, usercat, pipe, bootfile, 
swapdata, swapcode, ramap, userfile, killedobject); 

entrytype* (emptyentry, catentry, linkentry, fileentry, pipeentry, ecentry, 
killedentry); 

fs_info ■ record 

name : e__name ; 
dir__path : pathname; 
machinejLd : longint ; 
case otype : info_type of 
device_t, volume_t: ( 
io channel : integer; 
devt : devtype ; 

slot_no : integer; 

fsjsize : longint; 

vol_size : longint; 

blockstructured, mounted : boolean; 

opencount : longint ; 

privatedev, remote, lockeddev : boolean; 

mount_pending , unmount_pending : boolean; 

volname, password : e_name; 

fsversion, volnum : integer; 

volid : UID; 

blocksize, datasize, clustersize, filecount : integer; 

freecount : longint; 

DTVC, DTCC, DTVB, DTVS : longint; 

masterjcopy_id, copy__thread : longint; 

overmount_stamp : UID; 

privileged, writejprotected : boolean; 

master, copy, copy_flag, scavenge__flag : boolean; 

vol^lef tjmounted : boolean ); 

object__t : ( 
size : longint; 

psize : longint; (* physical file size in bytes *) 
lpsize : integer; (* logical page size in bytes for this file *) 
ftype : filetype; 

etype : entrytype; 
DTC, DTA, DTM, DTB, DTS : longint; 
refnum : integer; 
fmark : longint; 
acmode : inset ; 

nreaders, nwriters, nusers : integer; 
fuid : UID; 

eof , saf etymon, kswitch : boolean; 
private, locked, protected, master_file : boolean; 
file_scavenged, f ile__closed__byjOS , file_lef t_open : boolean ) 
end; 
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dctype =» record 

dcversion : integer; 
decode : integer; 

dedata : array [0..9] of longint; (* user/driver defined data *) 
end; 

t_waitlist « record (* wait list *) 

length : integer; 

refnum : array [0. .size_waitlist] of integer; 
end; 



t__eheader - records 

send_j?id : longint; 
event_type : longint; 
end; 



(* event header *) 

(* sender's process id *) 

(* type of event *) 



t_event_text « array [0. .size_etext] of longint; 
p_r_eventblk * ~r_eventblk; 
r_jeventblk ■ record 

eventjieader : tjeheader; 

event__text : t_event_text ; 
end; 

p__s_eventblk - A s__eventblk; 
s_eventblk - t_event^text; 



timejrec ■ record 

year : integer; 
day t 1..366; 
hour : -23.. 23; 
minute : -59.. 59; 
second : 0..59; 
msec : 0..999; 
end; 



(* Julian date *) 



chn_kind * (wait_ec, calljsc); 
t_chn__sts = record 

chn_type : chnjtcind; 

num_events : integer; 
openjrecv : integer; 
open_send : integer; 
ecjname : pathname; 
end; 

hourjrange =» -23.. 23; 
minutejrange * -5 9.. 59; 



(* channel status *) 

(* channel type *) 

(* number of events queued *) 

(* number of opens for receiving *) 

(* number of opens for sending *) 

(* event channel name *) 
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(* File System calls *) 

procedure MAKE_FILE (var ecode: integer; var path: pathname; label_size: integer); 
procedure MAKEJPIPE (var ecode: integer; var path: pathname; label__size: integer) ; 
procedure MAKE_CATALOG (var ecode: integer; var path: pathname; label_size: integer); 
procedure MAKEJLINK (var ecode: integer; var path, ref :pathname; label__size: integer); 
procedure KILL_OBJECT (var ecode: integer; var path: pathname); 

procedure UNKILL_FILE (var ecode: integer; refnum: integer; var new_name:e__name) ; 
procedure OPEN (var ecode: integer; var path: pathname; var refnum: integer; manip:mset); 
procedure CLOSE_OBJECT (var ecode: integer; refnum: integer); 



procedure READJDATA (var ecode 

refnum 

data_addr 

count 

var actual 

mode 

offset 



integer; 
integer; 
longint ; 
longint ; 
longint ; 
iomode ; 
longint ) ; 



procedure WRITEJDATA (var ecode : integer; 

refnum : integer; 
data_addr : longint; 

count : longint; 

var actual : longint; 

mode : iomode ; 

offset : longint); 

procedure FLUSH (var ecode: integer; refnum: integer); 

procedure LOOKUP (var ecode : integer; 

var path : pathname; 
var attributes : fs_info); 

procedure INFO (var ecode .'integer; refnum: integer; var refinfo:f s__info); 

procedure ALLOCATE (var ecode : integer; 

refnum : integer; 

contiguous : boolean; 

count : longint; 

var actual : longint); 

procedure TRUNCATE (var ecode : integer; refnum : integer); 

procedure COMPACT (var ecode : integer; refnum : integer); 

procedure RENAME__ENTRY ( var ecode: integer; var path: pathname; var newname : e_name ); 
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procedure READ_LABEL ( var ecode : integer; 

var path : pathname; 

da ta_addr : longint ; 

count : longint; 

var actual : longint ); 

procedure WRITEJLABEL ( var ecode : integer; 

var path : pathname; 

data_addr : longint; 

count : longint; 

var actual : longint ); 

procedure MOUNT ( var ecode: integer; var vname : e__name; var password : ejaame ; 
var de vname : e__name); 

procedure UNMOUNT ( var ecode: integer; var vname : e__name ); 

procedure SET_WORKING_DIR ( var ecode: integer; var path: pathname ); 

procedure GET_WORKING_DIR ( var ecode: integer; var path: pathname ); 

procedure SETJSAFETY ( var ecode: integer; var path: pathname; onjoff: boolean ); 

procedure DEvTCE_CONTROL ( var ecode: integer; var path: pathname; 

cparm : dctype ); 

procedure RESET_CATALOG (var ecode : integer; var path : pathname); 

procedure GET_NEXT__ENTRY (var ecode : integer; var prefix, entry : e_name); 

procedure SET_FILE_INFO ( var ecode : integer; 

refnum : integer; 
fsi : fs info ); 



(* Process Management system calls *) 
function My__ID : longint; 

procedure Info_Process (var errnum : integer; proc_id : longint; 

var proc_jLnfo : procinf oRec); 

procedure Yield__CPU (var errnum : integer; to_any : boolean) ; 

procedure SetPriority__Process (var errnum : integer; proc_id : longint; 

newjpriority : integer); 

procedure Suspend_J?rocess (var errnum : integer; procjLd : longint; 

susp family : boolean); 
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procedure Activate_Process (var errnum : integer; procJLd : longint; 

actJEamily : boolean); 

procedure Kill_Proces s (var errnum : integer; proc_id : longint); 

procedure Terminate_Process (var errnum : integer; event_ptr : p_s_eventblk); 

procedure Make_Process (var errnum : integer; var procjLd : longint; 

var progfile : pathname; var entryname : names tring; 
evntjrhnjref num : integer) ; 



(* Memory Management system calls *) 

procedure make_dataseg(var errnum: integer; var segname: pathname; 

memjsize, disc_size: longint; var refnum: integer; 
var segptr: longint; ldsn: integer; dstype: Tdstype); 

procedure killjdataseg (var errnum : integer; var segname : pathname); 

procedure openjdataseg (var errnum : integer; var segname : pathname; 

var refnum : integer; var segptr : longint; 
ldsn : integer); 

procedure close_dataseg (var errnum : integer; refnum : integer); 

procedure size_dataseg (var errnum : integer; refnum : integer; 

deltamemsize : longint; var newmemsize : longint; 
deltadiscsize: longint; var newdiscsize: longint); 

procedure info__dataseg (var errnum : integer; refnum : integer; 

var dsinfo : dsinfoRec); 

procedure setaccess_dataseg (var errnum : integer; refnum : integer; 

readonly : boolean); 

procedure unbind_dataseg (var errnum : integer; refnum : integer); 

procedure bind_dataseg(var errnum : integer; refnum : integer); 

procedure infq_ldsn (var errnum : integer; ldsn: integer; var refnum: integer); 

procedure flush_dataseg(var errnum: integer; refnum: integer); 

procedure mem_info( var errnum: integer; 

var swap space, dataspace, 

cur__codesize, max_codesize: longint); 

procedure info_address(var errnum: integer; address: longint; 

var refnum: integer); 
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(* Exception Management system calls *) 

procedure declare__excep_ hdl (var errnum : integer; 

var excep_name : t_ex_jiame; 
entry jpoint : longadr); 

procedure disable_jexcep (var errnum : integer; 

var excepjaame : t_ex__name; 
queue : boolean) ; 

procedure enable__excep (var errnum : integer; 

var excep__name : t_ex__name) ; 

procedure signal_excep (var errnum : integer; 

var excep_name : t_ex_name; 
excep_data : t_ex_data) ; 

procedure infq__excep (var errnum : integer; 

var excep_name : t_ex_name; 
var excepts tatus : tjexjats); 

procedure f lush_excep (var errnum : integer; 

var excep_name : t__ex_name); 

(* Event Channel management system calls *) 

procedure makejevent_chn (var errnum : integer; 

var event_chn_name : pathname); 

procedure kill_event_chn (var errnum : integer; 

var event_chn_name : pathname); 

procedure ope n_e vent _chn (var errnum : integer; 

var event_chn_name : pathname; 
var refnum : integer; 
var excep_name : t_ex_name; 
receiver : boolean) ; 

procedure close_event_chn (var errnum : integer; 

refnum : integer) ; 

procedure info_event_chn (var errnum : integer; 

refnum : integer; 
var chnjinfo : t_chn_sts); 

procedure wait__event_chn (var errnum : integer; 

var wait__list : tjwaitlist; 
var refnum : integer; 
event_ptr : p_r__eventblk); 
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procedure flush_event_chn (var errnum : integer; 

refnum : integer); 



procedure send__event_chn (var errnum : integer; 

refnum : integer; 
eventjptr : p_s_eventblk; 
interval : times tmp_interval; 
clktime : time rec); 



(* Timer functions system calls *) 

procedure delay_time (var errnum : integer; 

i nt e rval : t imes tmp_int e rval ; 
c lkt ime : t ime_r ec ) ; 

procedure get__time (var errnum : integer; 

var gmt_time : time_rec); 

procedure set_local__time_dif f (var errnum : integer; 

hour : hourjrange; 
minute : minute_range); 

procedure convert_time (var errnum : integer; 

var gmt_time : time__rec; 
var local_time : time__rec; 
to^gmt : boolean) ; 
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ADDITIONS TO THE OS 

This section documents all the changes to the OS that have occurred since 
the last release of the OS Reference Manual. When the manual is updated, 
the material will be deleted from this section. 



NEW OS PROCEDURES 

A new data segment call named Info_Address was added in release 5.2. This 
call returns the refnum of the data segment that maps to the address that 
the user specifies in the call. The definition of the call is: 

Infq__Ad dress (var errnum: integer; 
address: longint; 
var refnum: integer); 



where errnum is the return status of the call, address is the address that 
is converted to a data segment number, and refnum is the refnum of the data 
segment that maps to the address 'address' . 

Info_Address can return any of the following errors: 
303 - No data segment bound to the address 
314 - Address does not fall within the valid ldsn range 
1998 - Invalid parameter address 



MEM__INF0, defined below retrieves information about the memory resources 
that the calling process uses. 

MEM_INF0 (var errnum : integer 
var swapspace; 
da t as pace; 
cur_codesize; 
max_codes ize : longint ) 

where: 

swapspace * amount of system memory available (in bytes) 
for swapping 

dataspace =» amount of memory (in bytes) the calling process 
requires for its bound data areas. This value 
includes the stack of the process and the data 
segment for shared intrinsic data. 
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cur_codesize =» size (in bytes) of the calling segment. 

max_codesize - size (in bytes) of the longest code segment within 
the address space of the calling process. 

The Set_File_Info system call, added in release 5.2, alters certain status 
information associated with a file system object. The call format is: 

Set_File_Info (var ecode: integer; 

refnum: integer; 
fsi: fs info); 



where ecode is the error return code, refnum is the refnum of the object, 
and fsi is the fs information record that the OS calls LOOKUP and INFO use. 
Note that the object that refnum identifies must be open at the time of the 
call to Set_File_ Info. 

Set_File_Info alters the status information of the named object to conform 
to the values of the information record named in the call. Call INFO and 
set the values in fsi you want to change before calling this procedure. 

Currently, Set_File_Info can change the following status fields: 

o file_s cave nged 

o file_closed^by_jOS 

o file_left_open 

The Unkill_File call was added in release 5.3. It reverses the effect of 
the Kill_Object operation on an open file. Only objects of type file can 
be unkilled. A new catalog entry is created for the file with the name 
new_jaame. The call format is: 

Unkill_File (var ecode: integer; 

refnum: integer; 
var newjiame: e_name); 

Where ecode is the error return code, refnum is the refnum of the open 
file, and newjiame is the name the file is to be cataloged under. 

INTERFACE CHANGES 

The following interface changes were made in release 5.3. 

1. The Get_pev_Name system call has been removed from the OS user 
interface. 

The information that used to be returned by Get_jDev__Name is now 
available 

in the FS__INFO record returned by Lookup and Info. 
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2. The devnum field has been removed from the FS_INFO record 

3. A new field 

dirjpath: pathname 

has been added to the FS_INFO record. For Lookup/Info on an object, 
dir_path is the pathname of the directory containing the objects entry. 
Therefore, a unique pathname for an object can be constructed by 

concat(FS_INFO.dir_path, '-', FS__INFO.name) ; 

For lookup on a device, dir-path is the pathname of the directory for 
that device. 



DATA SEGMENT CHANGES 

From OS release 5.1 on, OPEN_DATASEG is much less sensitive to the values 
of LEOF and PEOF within the data segment being opened. The results of an 
OPEN_DATASEG call under various conditions are outlined below: 

Condition Resulting Data Segment 



< LEOF <» 128kb memory size * LEOF; disk size * PEOF 

PEOF * any value errnum ■ 

LEOF > 128kb errnum ■ 306 (data segment too big) 
PEOF * any value 

LEOF ■ memory size ■ PEOF; disk size » PEOF 

< PEOF <- 128kb errnum ■ -320 (a warning) 

LEOF = memory size - 128kb; disk size * PEOF 

PEOF > 128kb errnum - -320 (a warning) 

LEOF » memory size =512 ; disk size = 

PEOF ■ errnum ** -320 (a warning) 



Those conditons which result in a warning error (-320) should be checked 
via INFOJDATASEG to verify that the resulting data segment has the desired 
memory and disk sizes before the segment is used. 
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In release 5.2 of the Operating System the calling sequence for 
Make_JDataseg has changed to: 

Tdstype ■ (dsjshared, ds_private) 

Make_Dataseg (var errnum: integer; 

var segname: pathname; 

mem_size, disc_size: longint; 
var refnum: integer; 
var segptr: integer; 

ldsn : integer; 

dstype : Tdstype); 

All parameters are the same as before except dstype. Dstype now specifies 
whether the data segment created is shared or private. The segment is 
located on the disk that segname specifies. Note that a null segname is no 
longer valid. 

Info__Dataseg returns the attributes of a data segment in the record Dslnfo. 
Release 5.2 adds two values to this record: segptr and volname. segptr is 
of type longint and represents the base address of the data segment; 
volname is of type e_ name and represents the volume that contains the data 
segment • 



CHANGES TO LISABUG 

This section presents the additions and fixes to Lisabug that were made in 
the 5.2 release of the OS. These changes involve stack crawl and 
breakpoints. 

The stack crawl command, SC, is now very robust. It correctly lists all 
stack frames even in domain 0. 

This version of Lisabug allows you to run a program with the initial 
breakpoint set at the first instruction of the program. See the 
description of the D(ebug command in the section on the OS Shell in this 
manual for the details of this feature. 

You can now set a breakpoint in code that is not in memory. As the code is 
swapped in and out, the OS automatically restores the breakpoints 
associated with the code currently in memory. Note that although you can 
set breakpoints in code that is not in memory, you can only use symbols for 
the code, such as procedure names, when the code is in memory. Therefore, 
you must use the logical address form of the breakpoint command when 
setting a breakpoint in code not in memory. However, once the code is 
swapped in, you can use the symbolic form of the breakpoint. 
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Another added breakpoint command feature is a format for specifying 
breakpoints on a process basis. The syntax of the new format iss 

>br procid : address 

When the process specified by procid reaches 'address', the breakpoint is 
taken. However, if any other process reaches 'address', the breakpoint is 
not taken. If you don't specify a procid in a breakpoint command, the OS 
assumes the procid of the currently executing process (most application's 
programmers will probably use this mode). Note that to reflect the change 
of associating a breakpoint with a process, Lisabug now displays the procid 
of the currently running process as well as the domain currrently in 
effect. 

Although only the OS group will probably do this, if you wish to set a 

breakpoint in the Operating System, specify as the procid in the command. 

Using as the procid, causes all processes to take the breakpoint in the 
OS when they reach the specified address. 

ERROR CHANGES AND ADDITIONS 

Release 5.2 contains a new error for OpenJDataseg, MakeJDataseg, and 
SizeJDataseg. This error, 315, indicates that the operation could not be 
completed because it might cause a data lockout situation. 

OpenJDataseg can now return the warning -321. This warning indicates that 
the data segment was opened successfully, but the file system returned a 
warning that the data within the segment may not be valid because the data 
segment was open when the system crashed. 
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OS ERROR MESSAGES 

The following list of OS error messages is in ascending numerical order. 
However, the ordering scheme ignores the sign of the error number; the 
minus sign preceding an error number indicates that the message is a 
warning; the OS may or may not have completed the flagged action. 



no error 
PROCESS MANAGEMENT 

100 Specified process does not exist 

101 Specified process is a system process 

110 Invalid priority specified (must be . 1.. 255) (SetPriority_ Process) 

-115 Specified process is already suspended (Suspend_JProcess) 

-120 Specified process is already active (Activate_Process) 

-125 Sepcified process is already terminating (KillJProcess) 

130 Could not open program file 

131 Error while trying to read program file 

132 Invalid program file (incorrect format) 

133 Could not get a stack segment for new process 

134 Could not get a syslocal segment for new process 

135 Could not get a PCB for new process (no sysglobal space) 

136 Could not set up communication channel for new process 

138 Error accessing program file while loading 

139 Could not get a PLCB to load the program (no sysglobal space) 

141 Error accessing a library file while loading program (e.g. the 
library file containing required shared segment not found) 

142 Can't run protected file on this machine 

143 Program uses an intrinsic unit not found in the Intrinsic 
Library 

144 Program uses an intrinsic unit whose name or type does not 
agree with the Intrinsic Library 

145 Program uses a shared segment not found in the Intrinsic 
Library 

146 Program uses a shared segment whose name does not agree with 
the Intrinsic Library 

147 No space in syslocal for program file descriptor during 
process creation 

148 No space in the shared IU data segment for shared IU globals 
required by the program 

-149 Process was created, but the specified program file has been 

scavenged and altered 
-150 Process was created, but a library file required by the program 

has been scavenged and altered. 

EXCEPTION MANAGEMENT 

201 No such exception name declared 

202 No space left in the system data area for declare__execp_hdl 
or signal_excep. 

203 Null name specified as exception name. 
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MEMORY MANAGEMENT 

302 Invalid Idsn 

303 No data segment bound to an Idsn when there should be 

304 Data segment bound to an Idsn when it shouldn't be 

306 Data segment too large 

307 Input data segment path name is invalid 

308 Data segment already exists 

309 Insufficient disk space for data segment 

310 An invalid size has been specified: 

- memory size < 3 

- memory size of shared data segment > 128K 

- disk size < 

311 Insufficient system resources 

312 Unexpected file system error 

313 Data segment not found 

314 Invalid address passed to Info_Address 

315 Operation may cause a data lockout 

-320 Could not determine size of data segment. Defaults used 

were s memory size =* 512 bytes, disk size * bytes 

-321 Data segment open when the system crashed. Data possibly 

invalid. 



EVENT MANAGEMENT 

401 Invalid event channel name passed to make_jevent_chn : 
empty string or string longer than 16 characters 

402 No space left in system global data area for open__event_chn 

403 No space left in system local data area for open_eventj:hn 

404 Non-block structured device specified in pathname ~" 

405 Catalog is full in Make__Event_Chn or Open_Event_Chn 

406 No such event channel exists in Kill_Event_Chn 

410 Attempt to open a local event channel to send 

411 Attempt to open an event channel to receive when event 
channel already has a receiver 

-412 Event channel was left open and system crashed, 

Ope nJEvent Chn 
-413 Event channel was scavenged, QpenJ2vent__Chn 

413 Unexpected file system error in 0penJ2vent__Chn 

416 Cannot get enough disk space for event channel in 
Ope n_E ve nt__Chn 

417 Unexpected file system error in Close_Event__Chn 

420 * Attempt to wait on a channel that the calling process 

did not open 

421 WaitJEvent_Chn returns while waiting on an empty channel 
because a sender process was not able to successfully 
complete sending an event. 

422 Attempt to call wait_event_chn on an empty event-call 
channel 

423 Cannot find corresponding event channel after being 
» blocked (wait event chn) 
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424 



425 
426 
427 
428 

429 
430 

431 



432 
433 
440 
441 
445 
450 
600 



The actual amount of data returned while reading an event 
from a channel is not the same as the size of that event 
block in wait_event__chn (probably disk I/O failure) 
Event channel empty after being unblocked, Wait_Event_Chn 
Bad request pointer error returned in Wait_Event__Chn 
Wait_List has illegal length specified, Wait_Event_Chn 
Receiver unblocked because last sender closed, 
Wai t_Event_Chn 

Unexpected file system error in Wait_Event_Chn 
Attempt to send to a channel which the calling process 
does not have open 

The actual amount of data transferred while writing an 
event to a channel is not the same as the size of an 
event block in send_event_chn (disk is probably full) 
Sender unblocked because receiver closed in Send_J3vent__Chn 
Unexpected file system error in Send_ Event_Chn 
Unexpected file system error in Make_Event_Chn 
Event channel already exists in Make_Event__Chn 
Unexpected file system error in Kill_Event__Chn 
Unexpected file system error in Flush_Event_Chn 
See GENERAL 1/0 ERRORS below 



TWIGGY DISK 



606 
608 
609 
610 
613 
614 
617 
618 
623 
18xx 



Can't find sector (disk unformatted) 

See GENERAL 1/0 ERRORS below 

See GENERAL 1/0 ERRORS below 

See GENERAL 1/0 ERRORS below 

Unpermitted direct access to spare track with sparing enabled 

No disk present in drive 

Checksum error 

Can't format, or write-protected, or error unclamping 

Illegal device control parameters to Twiggy 

See "OTHER ERRORS" below 



GENERAL I/O 

600 Attempt to perform 1/0 operation on non 1/0 request 

602 No more alarms available during driver initialization 

-603 Warning - recoverable errors encountered during disk read 

605 Call to non-configured device driver 

608 Illegal length or disk address for transfer 

609 Call to non-configured device driver 

610 No more room in Sysglobal for I/O request 

615 Wrong call version to Twiggy 

616 Unpermitted Twiggy function 

619 No more room in Sysglobal for 1/0 request 

658 Premature end of file when reading from driver 

659 Corrupt file system header chain found in driver 
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TIME MANAGEMENT 



630 



631 
632 
634 
635 

636 
638 

639 



The time passed to delay__time, convert_time, or 

send_eventj:hn is such that the year is less than 1900 

or greater than 2035. 

Illegal Timeout request parameter 

No memory available to initialize clock 

Illegal Timed event id of -1 

Process got unblocked prematurely due to process 

t e rmina t ion ( delay_t ime ) 

Timer request did not complete successfully (delay_time) 

The time passed to delay__time or send_event_chn is more 

than 23 days from the current GMT time 

Illegal date passed to Set_JTime, or illegal date from 

system clock in Get Time 



RS-232 



640 
641 
642 
646 
647 
648 

649 



RS-232 driver called with wrong version number 

RS-232 read or write initiated with illegal parameter 

Unimplemented or unsupported RS-232 driver function 

No memory available to initialize RS-232 

Unexpected RS-232 timer interrupt 

Unpermitted initialization or required modem signals 

not present 

Illegal device control parameters to RS-232 



PROFILE DISK 

652 
653 
654 
655 
656 
658 
659 
660 
662 
663 
666 
670 
685 
18xx 

SERIAL DRIVER 



N-port driver not initialized prior to Profile 

No room in sysglobal to initialize Profile 

Hard error status returned from drive 

Wrong call version to Profile 

Unpermitted Profile function 

See GENERAL I/O ERRORS above 

See GENERAL I/O ERRORS above 

Cable disconnected 

Parity error 

Checksum error 

Timeout 

Bad command response from drive 

Eject not allowed this device 

See "OTHER ERRORS" below 



680 
682 
683 



Wrong call version to serial driver 

Unpermitted serial driver function 

No room in sysglobal to initialize serial driver 
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N-PORT CARD DRIVER 



686 
687 
688 



No room in sys global to initialize n-port card driver 
Unpermitted n-port card driver function 
Wrong call version to n-port card driver 



PARALLEL PRINTER 



690 
691 
692 
693 
694 
696 
698 

STARTUP 

700 

701 
702 
703 
704 
705 
706 
707 
708 
709 
710 

FILE SYSTEM 



Wrong call version to parallel printer 

Illegal parallel printer parameters 

N-port card not initialized prior to parallel printer 

No room in sysglobal to initialize parallel printer 

Unimp Lamented device control 

Out of paper 

Offline 



Mismatch between loader version number (in OS. OBJ) and 

operating system version number (in SYSTEM. OS. OBJ) 

OS exhausted its internal space during startup 

Cannot make system process 

Cannot kill pseudo-outer process 

Cannot create driver 

Cannot program NMI key 

Cannot (soft) initialize Twiggy 

Cannot (soft) initialize the file system volume 

Profile not readable 

Cannot map screen data 

Too many slot-based devices 



VmStuff; 
801 
802 
803 

806 
809 
810 
816 
819 
820 
821 
822 
SFilelO: 
825 
826 
828 
829 
835 
837 



IoResult <> on I/O using the Monitor (LISAIO) 

Asynchronous 1/0 request not completed successfully 

Bad combination of mode parameters (this is an internal 

error that should not occur when you run your code) 

Page specified is out of range (TFDM) 

Invalid arguments (page, address, offset, or count) (VM) 

The requested page could not be read in (VM) 

Not enough sysglobal space for file system buffers (initqvm) 

Bad device number (I0_INIT) 

No space in sysglobal for asynchronous request list 

Already initialized 1/0 for this device 

Bad device number (I0J) IS INIT) 

Error in parameter values (Allocate) 

No more room to allocate pages on device 

Error in parameter values (Deallocate) 

Partial deallocation only (ran into unallocated region) 

s-file number < or > maxfiles (illegal value) (SList_I0) 

Unallocated s-file or I/O error (FMapJtfgr) 



Roth 



50 



October 1, 1982 



Confidential 



Guide to OS 



838 

839 
841 
843 
847 
848 
849 
852 
854 
855 
856 
857 
861 
864 
866 
867 
868 
869 
870 
FS__Primitives 
871 
872 
873 
874 
875 
879 
881 
882 
883 
884 
885 
886 
887 
888 
890 
891 
892 
894 
895 
896 

FS Init: 

¥97 
FS__Interface: 

921 

922 

926 

927 

941 

944 

945 

946 

947 



Map overflow: s-file too large (this error obsolete from 

release 5.2 of the OS on) 

Attempt to compact file past PEOF (FMapJMgr) 

Unallocated s-file or I/O error (GetJPSlze) 

Requested exact fit, but one couldn't be provided (AppendPages) 

Requested transfer count is <* (DatalO) 

End-of-file encountered 

Invalid page or offset value in parameter list 

Bad unit number (FlushFS) 

No free slots in s-list directory (too many s-files) (New__SFile) 

No available disk space for file hints 

Device not mounted 

Empty, locked, or invalid s-file (Kill_SFile) 

Relative page is beyond PEOF (bad parameter value) (AbsPage) 

No sys global space for volume bitmap ( Real_Mount , RealJJnmount ) 

Wrong FS version or not a valid Lisa FS volume 

Bad unit number (Realjlount, RealJJnmount ) 

Bad unit number (Defjlount, Def __Unmount ) 

Unit already mounted (mount) /no unit mounted (unmount) 

No sys global space for DCB or MDDF (mount) 

Parameter not a valid s-file ID (OpenJSFile) 

No sys global space for s-file control block 

Specified file is already open for private access 

Device not mounted 

Invalid s-file ID or s-file control block (Close__SFile) 

Attempt to postion past LEOF (Direct_JEO) 

Attempt to read empty file (File 10) 

No space on volume for new data page of file 

Attempt to read past LEOF 

Not first auto-allocation, but file was empty 

Could not update filesize hints after a write (fileio) 

No sys local space for I/O request list 

Catalog pointer does not indicate a catalog (bad parameter) 

Entry not found in catalog (Lookup_by_ename) 

Entry by. that name already exists (Make_Entry) 

Catalog is full, or was not as catalog 

Illegal name for an entry 

Entry not found, or not a catalog (KillJSntry) 

Invalid entry name (killjentry) 

Safety switch is on — cannot kill entry (kill_entry) 



Invalid bootdev value 

Pathname invalid or no such device (Make_File) 

Invalid label size (Make_File) 

Pathname invalid or no such device (MakeJPipe) 

Invalid label size (Make_Pipe) 

Pathname invalid or no such device (KilljDbject) 

Object is not a file (Unkill_File) 

File is not in the killed state (Unkill_File) 

Pathname invalid or no such device (Open) 

Not enough space in syslocal for file system ref db 
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948 
949 
950 

951 
952 
954 
955 
956 
957 
958 
959 
960 
961 
962 
963 
964 

965 
966 
967 
968 
971 
972 
974 
977 
978 
979 
981 
982 

983 
985 
986 
987 
988 
989 
990 
994 
995 
999 

1021 
1022 
1023 
1024 
1031 
1032 
1033 
1041 
1042 
1043 
1051 
1052 



Entry not found in specified catalog (Open) 

Private access not allowed if file already open shared 

Pipe already in use, requested access not possible OR 

dwrite not allowed for pipe 

File is already opened in private mode (open) 

Bad refnum (Close__0bject) 

Bad refnum (Read__data) 

Read access not allowed to specified object 

Attempt to position FMARK past LE0F not allowed 

Negative request count is illegal (read__data) 

Non-sequential access is not allowed (read_data) 

System resources exhausted 

Error writing to pipe while an unsatisfied read was pending 

Bad refnum (writejdata) 

No WRITE or APPEND access allowed 

Attempt to position FMARK too far past LEOF 

Append access not allowed in absolute mode 

Append access not allowed in relative mode 

Internal inconsistency of FMARK and LEOF (warning) 

Non-sequential access is not allowed (writejdata) 

Bad refnum (Flush) 

Pathname invalid or no such device (Lookup) 

Entry not found in specified catalog 

Bad refnum (Info) 

Bad refnum (allocate) 

Page count is non-positive (allocate) 

Not a block structured device (allocate) 

Bad refnum (Truncate) 

No space has been allocated for specified file 

Not a block structured device (truncate) 

Bad refnum (Compact) 

No space has been allocated for specified file 

Not a block structured device (compact) 

Bad refnum (Flush_Pipe) 

Caller is not a reader of the pipe 

Not a block structured device (flushjpipe) 

Invalid refnum (Set_File_Info) 

Not a block-structured device (Set_JFile__Info) 

Asynchronous read was unblocked before it was satisfied. 

This may occur during process termination. 

Pathname invalid or no such entry (Rename_Entry) 

No such entry found (rename__entry) 

Invalid newname, check for '-' in string (rename_entry) 

New name already exists in catalog (renamejentry) 

Pathname invalid or no such entry (Read_Label) 

Invalid transfer count ( read__label ) 

No such entry found (read_label) 

Pathname invalid or no such entry (Wri te_Label ) 

Invalid transfer count (write__label) 

No such entry found (write_label) 

No device or volume by that name (mount) 

A volume is already mounted on device 
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1053 Attempt to mount the temporarily unmounted boot volume 
just unmounted from this machine (MOUNT) 

1054 The bad block directory of the diskette is invalid. 
The mount is not completed (realjmount) 

-1059 Warning, the bad block directory of the diskette is almost 

full or difficult to read. The mount is completed (real_mount) 

-1060 Attempt to mount a foreign boot disk following a temporary 
unmount 

1061 No device or volume by that name (Unmount) 

1062 No volume is mounted on device 

-1063 Warning, attempt to mount a temporarily unmounted boot 

volume that was either unmounted from another machine or 
was not the most recently unmounted boot volume. The 
mount is completed (MOUNT) 
1071 Not a valid or mounted volume for working directory 

1091 Pathname invalid or no such entry (SetjSafety) 

1092 No such entry found (setjsafety) 
1101 Invalid device name (DEVICE_C0NTR0L) 

1121 Invalid device, not mounted, or not a catalog (reset__catalog) 

1128 Invalid pathname, device, or volume not mounted (getjdevjiame) 

1130 File is protected; cannot open due to protection violation 
get_open_lis t 

1131 No device or volume by that name 

1132 No volume is mounted on that device 

1133 No more open files in the file list of that device 

(no files, data segments, event channels open on that device) 
regjopenJLis t 

1134 Cannot find space in sysglobal for open file list 

1135 Cannot find the open file entry to modify 

f sjutilities calls: 

1136 Boot volume not mounted (f sjutility, ubd) 

1137 Boot volume already unmounted (f sjutility, ubd) 

1138 Caller cannot have higher priority than system 
processes when calling ubd (f sjutility, ubd) 

1141 Boot volume was not unmounted when calling rbd 

1142 Some other volume still mounted on the boot device when 

calling rbd 

1143 No sysglobal space for MDDF to do rbd 

1144 Attempt to remount a volume which is not the temporarily 
unmounted boot volume from the same machine (rbd) 

1145 No sysglobal space for bit map to do rbd 

1159 fs__shutdown is not allowed while boot volume unmounted 
but operation is carried out 

fs__shutdown calls: 

1158 Track-by-track copy buffer is too small 

1159 Shutdown requested while boot volume was unmounted 

1160 Destination device too small for track-by-track copy 

1161 Invalid final shutdown mode 

1162 Power is already off 
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fsjutilities calls: 

1163 Illegal command 

1164 Device is not a Twiggy device 

1165 No volume is mounted on the device 

1166 A valid volume is already mounted on the device 

1167 The Device is not blocks true tu red 

1168 Device name is invalid 
newvolume (volume initialization): 

1169 Could not default mount volume before initialization 

1170 Could not mount volume after initialization 

1171 '-'is not allowed in a volume name 

1172 No space available to initialize a bitmap for the volume 
WARNINGS! from opening a file or mounting a volume: 

-1173 File was last closed by the OS 

-1174 File was left open or volume was left mounted, and system crashed 

-1175 File or volume was scavenged 

When these warnings occur on an OPEN call for a file or a MOUNT 
call for a volume, the OS goes ahead and opens the volume/file 
for access as usual. HOWEVER, the contents of the file might 
be inconsistent. 

CIRCULAR PIPES: 



1176 

1177 
1178 

1180 

1181 

1182 

1183 
1184 

1186 

1188 

1190 



Cannot read from a pipe more than half of the allocated 

physical size (read__data) 

Cannot cancel a read request for a pipe (read_data) 

Process waiting in read_data for pipe data got unblocked 

because the last writer of the pipe has closed it (readjdata) 

Cannot write to a pipe more than half of the allocated 

physical size (writejdata) 

No system space left for request block for pipe (writejdata) 

Writer process to a pipe got unblocked before the request 

was satisfied (this can occur during process termination) 

(writejdata) 

Cannot cancel a write request for a pipe (writejdata) 

Process waiting in write_data for pipe space got unblocked 

because the reader closed the pipe (writejdata) 

Cannot allocate space to a pipe while it has data wrapped 

around (allocate) 

Cannot compact a pipe while it. has data wrapped around 
( compact ) 

Attempt to access a page that is not allocated to the 
pipe (absrelbyte) 



OTHER: 
1196 
1197 
1198 
1199 
1200 
1201 



Something is still open on device— cannot unmount (real_unmount) 
Volume is not formatted or cannot be read (defjnount) 
Negative request count is illegal (writejdata) 
Function or procedure is not yet implemented 
Illegal volume parameter 
Blank file parameter 
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1202 Error writing destination file 

1203 Invalid UCSD directory 

1204 File not found 

1210 Boot track program not executable 

1211 Boot track program too big 

1212 Error reading boot track program 

1213 Error writing boot track program 

1214 Source file not found 

1215 Can't write boot tracks on that device 

1216 Couldn't create/close internal buffer 

1217 Boot track program has too many code segments 

1218 Couldn't find configuration information entry 

1219 Couldn't get enough working space 

1220 Premature EOF in boot track program 

1221 Position out of range 

1222 No device at that position 

18xx Error number xx from Boot ROM or Twiggy ROM. Likely errors 

appear below 

1807 No disk in Twiggy drive 

1820 Write protect error on Twiggy 

1822 Unable to clamp Twiggy 

1882 Bad response from Profile 

1885 Profile timeout error 

1998 Invalid parameter address 

1999 Bad refnum 

The pathname error codes (921, 926, 941, 946, and 971) often mean that the 
volume specified in the pathname is not mounted. If error 966 occurs 
while writing a file using the FTP utility, you probably ran out of space 
on the destination volume. 
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Operating System Error Codes by Procedure 



PROCESS MANAGEMENT 

Note that Yield_CPU and Terminate_Process return no errors 

Returned by all procedures except Make_Process 

100 Specified process does not exist 

101 Specified process is a system process 

SetPriority__Process 

110 Invalid priority specified (must be 1..255) 

Suspend__Process 
-115 Specified process is already suspended 

Act ivat e__Proces s 
-120 Specified process is already active 

Kill_J?rocess 
-125 Specified process is already terminating 



Make__Process 
130 
131 

132 
133 

134 
135 
136 
138 
139 
141 



142 
143 



144 
145 
146 
147 
148 
-149 
-150 



Could not open program file 

Error while trying to read program file 

Invalid program file (incorrect format) 

Could not get a stack segment for new process 

Could not get a syslocal segment for new process 

Could not get a PCB for new process (no sysglobal space) 

Could not set up communication channel for new process 

Error accessing program file while loading 

Could not get a PLCB to load the program (no sysglobal space) 

Error accessing a library file while loading program 

(e.g. library file containing shared segment required by 

program not found) 

Can't run protected file on this machine 

Program uses an intrinsic unit not found in the Intrinsic 

Library 

Program uses an intrinsic unit whose name or type does not 

agree with the Intrinsic Library 

Program uses a shared segment not found in the Intrinsic 

Library 

Program uses a shared segment whose name does not agree 

with the Intrinsic Library 

No space in syslocal for program file descriptor during 

process creation 

No space in the shared IU data segment for shared IU 

globals required by the program 

Process was created, but the specified program file has 

been scavenged and altered 

Process was created, but a library file required by the 

program has been scavenged and altered 
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EXCEPTION MANAGEMENT 



Returned by all procedures 
1998 Invalid parameter address 

Declare_excep_hdl 

201 No such exception name declared 

202 No space left in the system data area 

203 Null name specified as exception name. 

Disable__excep 

201 No such exception name declared 

203 Null name specified as exception name. 

Enable_excep 

201 No such exception name declared 

203 Null name specified as exception name. 

Info^excep 

201 No such exception name declared 

203 Null name specified as exception name. 

Flushjexcep . 

201 No such exception name declared 

203 Null name specified as exception name. 

Signal__excep 

201 No such exception name declared 

202 No space left in the system data area 

203 Null name specified as exception name. 



MEMORY MANAGEMENT 

Returned by all procedures 

1998 Invalid parameter address 

Returned by all procedures except INFOJLDSN, MAKE^DATASEG , OPENJDATASEG, 
KILLJDATASEG, and MEM__INF0 

1999 Bad refnum 

Note that SETACCESSJDATASEG and INFOJ)ATASEG return only 1998 and 1999 
and that MEM_INF0 returns only 1998 

INF0_LDSN 

302 Invalid ldsn 

303 No data segment bound to an ldsn when there should be 

0NBINDJDATASEG 

303 No data segment bound to an ldsn when there should be 

BINDJ)ATASEG 
. 302 Invalid ldsn 

304 Data segment bound to an ldsn when it shouldn't be 
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MAKE_DATASEG 

302 Invalid ldsn 

304 Data segment bound to an ldsn when it shouldn't be 

306 Data segment too large 

307 Input data segment path name is invalid 

308 Data segment already exists 

309 Insufficient disk space for data segment 

310 An invalid size has been specified: 

- memory size <■ 

- disk size < 

311 Insufficient system resources 

312 Unexpected file system error 
315 Possible data lockout 

0PENJ3ATASEG 

302 Invalid ldsn 

304 Data segment bound to an ldsn when it shouldn't be 

306 Data segment too large 

307 Input data segment path name is invalid 

311 Insufficient system resources 

312 Unexpected file system error 

313 Data segment not found s 
315 Possible data lockout 

-320 Warning: could not determine size of data segment. 
The following defaults were used: 

- memory size * 512 bytes 

- disk size - bytes 

-321 Data segment open when system crashed 

CLOSEJDATASEG 

312 Unexpected file system error 

KILL_DATASEG 

307 Input data segment path name is invalid 

312 Unexpected file system error 

313 Data segment not found 

SIZEJ3ATASEG 

304 Data segment being grown into an LDSN already in use 
306 Data segment too large 

309 Insufficient disk space for data segment 

310 An invalid size has been specified: 

- memory size <■ 

- memory size of shared data segment > 128K 

- disk size < 

312 Unexpected file system error 

315 Possible data lockout 

FLUSHJDATASEG 

312 Unexpected file system error 

INFO_ADDRESS 

303 No data segment bound to the address 

314 Address does not fall within valid ldsn range 
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EVENT MANAGEMENT 

Returned by all procedures 

1998 Invalid parameter address 

MakeJEvent_Chn 

401 Invalid event channel name passed to Make_Event_Chns 

empty string or string longer than 16 characters 

404 Non-block structured device specified in pathname to 
Make_Event_Chn , KillJEvent_Chn, or Open_Event_Chn 

405 Catalog is full in Hake_ Event_Chn 

440 Unexpected file system error in Make_Event_Chn 

441 Event channel already exists in Make_JEvent_Chn 

Kill_Event_Chn 

401 Invalid event channel name passed to Kill_Event_Chn: 

empty string or string too long 
404 Non-block structured device specified in pathname 

406 No such event channel exists in Kill__Event__Chn 
445 Unexpected file system error in Kill_Event_Chn 

Ope n_Event__Chn 

201 No such exception name declared 

401 Invalid event channel name passed to 0pen_Event__Chn : 
empty string or string too long 

402 No space left in system global data area for 0pen_Event_Chn 

403 No space left in system local data area for 0penJSvent_Chn 

404 Non-block structured device specified in pathname 
406 No such event channel exists in 0pen_Event__Chn 

411 Attempt to open an event channel to receive when event 

channel already has a receiver 
-412 Event channel was left open and system crashed, 

pe nJSve nt_Chn 
-413 Event channel was scavenged, 0pen_Event__Chn 

413 Unexpected file system error in OpenJSventjChn 

416 Cannot get enough disk space for event channel at open 
Returned when the event channel is local: 

405 Catalog is full in 0penJSvent__Chn 

410 Attempt to open a local event channel to send 

Close_Event_Chn 

201 No such exception name declared 

417 Unexpected file system error in Close_J2vent_Chn 

1999 Bad refnum 

Inf o__Event jChn 
1999 Bad refnum 
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Wait_Event 
402 
420 

421 



422 
423 
424 



425 
426 
427 
428 
429 
1999 



Chn 



No space left in system global data area 

Attempt to wait on a channel that the calling process 

did not open 

Wait_Event_Chn returns while waiting on an empty channel 

because a sender process was not able to successfully 

complete sending an event 

Attempt to call Wait_Event_Chn on an empty event-call channel 

Cannot find corresponding event channel after being blocked 

The actual amount of data returned while reading an event 

from a channel is not the same as the size of an event 

block in Wait__Event_Chn (probably disk I/O failure) 

Event channel empty after being unblocked 

Bad request pointer error return from Can_Aread__Pipe 

Wait__List has illegal length specified, WaitJSvent_Chn 

Receiver unblocked because last sender closed, Wait_Event_Chn 

Unexpected file system error in Wait_Event_Chn 

Bad ref num 



Flus h_Event_Chn 

450 Unexpected file system error in FlushJEvent__Chn 

1999 Bad ref num 



Send Event Chn 



430 
431 



432 

433 

1999 



Attempt to send to a channel which the calling process 
does not have open 

The actual amount of data transferred while writing an 
event to a channel is not the same as the size of an 
event block in Send_Event_Chn (disk is probably full) 
Sender unblocked because receiver closed in Send_J£vent_Chn 
Unexpected file system error in Send_Event__Chn "~ 
Bad refnum 



TIME MANAGEMENT 

Returned by all procedures: 
(Note that this is the only error message that Set_JLocal_JTime_Dif f 

returns) 
1998 Invalid parameter address 



DelayJTime 
630 



632 
635 



636 
638 



The time passed to Delay Time, Convert_Time, or 

Send_Event_Chn is such tTTat the year is less than 1900 

or great er"~than 2035 

No space in sys global 

Process got unblocked prematurely due to process 

termination (DelayJTime) 

Timer request did not complete successfully 

The time passed to DelayJTime or Send_Event_Chn is more 

than 23 days from the current GMT time 
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Convert_Time 

630 The time passed to Delay_JTime, ConvertJTime , or 

Send_Event_Chn is such that the year is less than 1900 
or greater than 2035 

Get Time 

639 Year not between 1981 and 1995 in GetJTime or Set_time< 
In GetJTime the error indicates a dead battery. 

SetJTime 

639 Year not between 1981 and 1995 in GetJTime or SetJTime, 

PWBT 

1210 Boot track program not executable 

1211 Boot track program too big 

1212 Error reading boot track program 

1213 • Error writing boot track program 

1214 Source file not found 

1215 Can't write boot tracks on that device 

1216 Couldn't create/close internal buffer 

1217 Boot track program has too many code segments 

1218 Couldn't find configuration information entry 

1219 Couldn't get enough working space 

1220 Premature EOF in boot track program 

PFTP 

1200 Illegal volume parameter 

1201 Blank file parameter 

1202 Error writing destination file 

1203 Invalid UCSD directory 

1204 File not found 

Get Config__Name 

1121 Position out of range 

1222 No device at that position 

Disk_Likely 

1221 Position out of range 

1222 No device at that position 
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OS LOADER DIAGNOSTICS 
Error Message 
FILE SYSTEM VERSION" MISMATCH 

FILE SYSTEM CORRUPT 

MEMORY EXHAUST 

SYSTEM CODE FILE NOT FOUND 

SYSTEM CONFIGURATION FILE 
NOT FOUND 

BOOT DEVICE READ FAILED 

CODE FILE CORRUPT 
TOO MANY OS SEGMENTS 
SYSTEM DEBUG FILE NOT FOUND 
PROGRAM NOT EXECUTABLE 

SYSTEM LOW LEVEL DRIVER FILE 
NOT FOUND 

CONFIGURATION FILE NOT USABLE 

WRONG DRIVER 



RANGE ERROR, OR UNKNOWN BOOT 
ERROR 



Cause or Description 

The boot tracks don't know 
the right file system version 

Either damaged file system or 
damaged contents 

The OS will not fit 

Cannot find SYSTEM. OS 

Cannot find SYSTEM. CONFIG 

Device could not be read for 
whatever reason 

Refers to SYSTEM. OS 

Refers to SYSTEM. OS 

Cannot find SYSTEM. DEBUG 

Refers to SYSTEM. OS, SYSTEM.DEBUG 
or SYSTEM. LLD 

Refers to SYSTEM. LLD 

Refers to SYSTEM. CONFIG 

For instance, storing a 
Twiggy driver on a Profile 

A loader bug 
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SYSTEM ERRORS 

A system error 1 indicates that something has r gone seriously awry within the 
Operating System code. When *fc system error occurs, the Operating System 
reports the errot and stops. Please report the occurrence of any system 
errors toJ r t:he Operating System groupi 

Common system errors: 

10102 Error while creating System. Shell during Startup 

ld26i Hardware exception (divide by zero, for example) 

in Operating System code 



EXCEPTIONS 

During execution applications can field hardware exceptions. If such an 
exception occurs, the system displays one of the following messages: 

Bus error or address error excentic-n: 

EXCEffl^tn^ process of gid <gggg> 

Processes about to be terminated. 

access address * <aaaaaaaa> =» mmu# <mmm> (segment name), offset <oooo> 

inst reg ■ <rrrr> sr * <ssss> pc - <PPPPPP> 

saved registers at <xxxxxxxx> 

Going to Lisabug, type g to continue 

Any other hardware exception: 

EXCEPTION in process of gid <gggg> 
Process is about to be terminated, 
sr * <ssss> pc = <pppppp> 

saved registers at <xxxxxxxx> 
Going to Lisabug, type g to continue 

where: 

<ggg8> is the global ID of the process that incurred the exception. 
<aaaaaaaa> is the address that caused the bus or address error 
<mmm> is the segment number represented by <aaaaaaaa> and 
<oooo> is the offset within that segment 

<rrrr> is the value of the instruction register at the time of the exception 
<ssss> is the value of the status register at the time of the exception 
<pppppp> is the value of the program counter at the time of the exception 
<xxxxxxxx> is the address of the saved register information 

All numbers displayed are decimal; the segment name is displayed only if 
the segment number makes sense to the Operating System. 
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If the exception is divide by zero, overflow, or CHK out of bounds, the 
process is not terminated and the line to that effect is not shown. If 
the process has declared an exception handler for £ this exception, tha^ 
handler is entered after you type g to Lisabug, and the process thejn ,, 
continues execution. If no handler has been cleciareci, the 'sy'f tern §££a\i%fc 
handler terminates the process. If the exception is. a bus error and* the 
segment name is 'stack seg', a stack overflow" has probably occurred. ^"The 
Operating System cannot currently recover from this error. 

If the exception occurs in Operating System code, the displays are the same", 
as given above except that the first two lines aire replaced by: 

EXCEPTION in system code! 

If you type g in Lisabug after this exception, a system error 10201 occurs 
and you must reboot. 

You should use release 7.4 or later of the Monitor because in these 
versions the Lisabug register display is the user's regis.ter^jdi^play^and 
the user can use the stack crawl command to find the calling procedures. 
You should not examine the memory location <xxxxxx> that contains HS^e-)? -j 
saved registers because the debugger saves the system's regis ters^ |:her£» 
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